Outside Looking In

Modern Web Applications

joeaseo — Wed, 25 Aug 2021 20:05:24 +0000

A web application is a computer program that uses a browser to perform tasks over the Internet. Many modern web applications (such as Google Docs) have evolved to implement many coordinated user functions and tasks traditionally associated with desktop software (such as Microsoft Office). Current browsers also have built-in support for open-source standards such as JavaScript, HTML5, and Cascading Style Sheets (CSS) that reduce the dependency on proprietary browser plugins such as Adobe Flash to run rich interactive content (such as streaming audio and video).

Modern web applications may require tasks performed over the Internet with an application server (such as identity management). In such cases, web applications use a combination of server-side scripts (Python or PHP) to handle the storage and retrieval of the information, and client-side scripts (JavaScript and HTML) to present the information to end users.

See the following resources for more information

Responsive Web Design

The global Internet population as of October 2019 reached 4.48 billion active users. Mobile devices have a 52.1% share worldwide compared to the desktop share of 44.2%.Responsive web design creates dynamic changes to the browser layout of a modern web application displayed on a desktop computer or mobile device . As a user switches between a desktop computer and a mobile device, the web application can accommodate the screen orientation, display resolution, and image size.

See the following resources for more information:

Web Services

Web services are computer programs or data sources that use server-side scripts to handle the storage and retrieval of information over a standard web protocol (HTTP or HTTPS). Web services are designed to communicate with other computer programs using application program interfaces (APIs) rather than interact directly with end users.

XML (eXtensible Markup Language) and JSON (JavaScript Object Notation) are the most common text-based formats for server-side scripts. These standard formats can be easily recognized and parsed by a computer program that receives the data.

REST (REpresentational State Transfer) is a type of web service that uses standard web protocols (HTTP or HTTPS) to access a uniform and predefined set of stateless operations for a web service. REST APIs can structure data into JSON or XML machine-readable formats for server-side scripts,

http://dummy.restapiexample.com/api/v1/create

REST API Example

SOAP (Simple Object Access Protocol) is a type of web service that simply adds a header to each XML message before it is transferred over HTTP as a server-side script.

xmlns:soap=”http://www.w3.org/2003/05/soap-envelope/”

soap:encodingStyle=”http://www.w3.org/2003/05/soap-encoding”>

…

SOAP Example

See the following resources for more information:

Just In Time

joeaseo — Tue, 15 Sep 2020 03:55:13 +0000

As customer requirements demand more flexibility and quicker response in project planning and implementation, companies are adopting agile development processes that focus more on working software than formal detailed specifications.

The impact on technical documentation (from user guides to online help) is huge when a project team adopts an agile development process. No longer can writers use formal specifications as a negotiating point with project teams to determine the number, scope, or schedule of document deliverables. Likewise

Agile Development Principles

The foundation of agile development are principles where the priority to satisfy customer requirements

Working software is the primary measure of progress.
Business people and developers must work together throughout the project.
Requirements, plans, and results are evaluated continuously so teams have a natural mechanism for responding to change quickly..

User Stories

A user story is employed in agile development to justify the effort to implemenr a new features (or modify an existing feature) A user story is a definition of a scenario where a goal is accomplished. A user story takes into account:

The type of user (eg, end user, system administrator, software developer).
The background, knowledge, experience, and training of the user.
The needs and interests of the user.
The goals of the user.

A user story describes the use of a product from a user’s point of view. The following template can be used to define a user story:

As a , I want , so that .

For example, a user story can look like this:

As an end user, I want to be able to log in to my account, so that I can view my profile.

Tasks

A user story is employed in agile development to justify the effort to implement a new feature (or modify an existing feature):

Users and developers must work together daily throughout the project.
Accept changing requirements, even late in development.
The team reflects on how to become more effective, then makes continuous adjustments..

A user story can be broken broken into tasks in order track the effort to implement a new feature (or modify

The following template can be used to define a task:

As a <resource>, I want , so that .

Estimated Effort:

Actual Effort:

Resource is an involved party that input should be gatheredIn an open source project, this can include developers, testers, users, and documentation writers. In an enterprise environment, feedback from customers is required, along with input from developers, support teams, product management, and content-strategy roles.
Estimated effort is the planned amount of time (typically expressed in hours) that is needed to accomplish a task in order to complete a user story
Actual effort is the actual amount of time (typically expressed in hours) that is needed to accomplish a task in order to complete a user story. The team reflects on how to become more effective, then makes continuous adjustments..

For example, a task description can look like this:

As an end user, I want to be able to verify the login dialog , so that I can change my password.

Estimated Effort: 16 hours

Actual Effort:

Continuous Delivery

The foundation of agile development is that software is planned, implemented, and tested “ so that project teams work closely with customers as requirements change, rather than treat change as an impediment to the development process.

Deliver working software frequently,
Continuous attention to technical excellence and good design enhances agility.
At regular intervals, the team reflects on howto become more effective, then tunes and adjustsits behavior accordingly.
The most efficient and effective method of conveying information to and within a project is face-to-face conversation.

Following agile development principles, a project team can meet on a daily or weekly iteration to provide the status by user story and related tasks :

Accomplishments: User story and related tasks are completed by resource, estimated effort and actual effort
Planned: User story and related tasks being planned by resource and estimated effort
Blockers: The actual effort expended on user story and related tasks exceeds the estimated effort and caanot be completed cannot

Kanban is a popular framework used to implement agile software development. It requires real-time communication of capacity and full transparency of work. Work items are represented visually on a kanban board, allowing team members to see the state of every piece of work at any time.

Agile Documentation

,Writers can no longer rely on formal specifications to provide the gist of the information that will be fleshed out during the draft development and review cycle. Instead, the de-emphasis on formal specifications in agile development means that writers must be able to install and configure the software from working prototypes to the final version in order to create the needed task, reference, and conceptual documentation.

Scott W. Ambler wrote an article on the document issues for agile development. Some of the insights that he shares are:

Write documents if that’s the best way to achieve relevant goals, but there are often better ways to achieve these goals than static documentation (such as an online help system that focuses only on a single product release or version).
Document information that is stable (not speculative).
Seek (then act) on feedback on a regular basis throughout the document draft and review process.

Think Short

Make sure your document is clear and concise. This means short sentences, short paragraphs, and short procedures.. Use as few words as possible to get ideas and information across. Likewise, focus on key ideas and explain them in simple, direct language..Provide information that readers need as they need it.

Think Topics

Break up the information into individual topics . A topic consists of a single page of information. Readers should be able to get the information they need—and only that information-—from a specific topic. To make that happen, choose which topics to include in your document and decide how to organize them:

Think Information Types

Writers can follow information design principles (derived from DITA) to organize page-length topics into such information types as:

Concept: Descriptive information so a user can understand the background and context of a subject.
Task: Step-by-step procedure
Reference: Specialized information (such as an application program interface (API)

Concept topics present descriptive information so the user can understand the background and context of the product. .Here is an example of a concept topic;

What is an omelet?

Types of omelets
Omelet ingredients
Preparing omelets

Task topics only explain the features of the product that need to be understood to achieve the defined goals in a step-by-step manner. Here is an example of a task topic:

To make an omelet:

Prepare ingredients.
Combine ingredients.
Fry omelet mixture.

Reference topics focus on product features. It lists and describes the various attributes of a product and tells the user how to make use of them. Here is an example of a reference topic:

Using onions

Peeling onions
Cutting onions
Frying onions

Think Topic Navigation

You may wind up with a lot of individual page-length topics in your document. To connect those topics. add explicit hyperlinks between topics. Place those hyperlinks at the end of each topic with a section heading such as See Also or Related Topics. Each section heading should contain two or more hyperlinks that that reference overview, concept, and reference topics that are related to the current topic.

If you need to link to information outside the scope of your document, make sure that the hyperlink opens in a new browser window or tab. That sends the reader to another topic while also keeping them on your topic.

Agile Documentation User Stories and Tasks

A. As a project manager, manage kanban workflow.

Task A1: Define project user stories
- Description: Define user stories and related tasks
- Assigned To:
- Estimated Effort:
Task A2: Define project kanban board
- Description: Define criteria for Backlog, Planned, In-Progress, Review, and Complete stages
- Assigned To:
- Estimated Effort:
Task A3: Create weekly status report
- Description: Track weekly progress of New, Backlog, Planned, In-Progress, Review user stories and related tasks
- Assigned To:
- Estimated Effort:

B. As a writer, achieve proficiency with information design principles.

Task B1: Audience Analysis
- Description: Goals of an audience (end users, system administrators, and developers) and information that each audience needs
- Assigned To:
- Estimated Effort:
Task B2: Information Types
- Description: Organizing information by DITA principles (overview, task, reference)
- Assigned To:
- Estimated Effort:
Task B3: Topic-based Authoring
- Description: Organizing information into individual overview, task, reference tasks
- Assigned To:
- Estimated Effort:
Task B4: Topic Navigation
- Description: Navigating individual overview, task, reference tasks using hyperlinked cross-references
- Assigned To:
- Estimated Effort:
Task B5: Create an overview article for using a kanban in technical writing
- Description: Create a topic-length overview article for end users that includes topic cross-references
- Assigned To:
- Estimated Effort:
Task B6: Create a task article for using a kanban in technical writing
- Description: Create a topic-length task article for end users that includes topic cross-references
- Assigned To:
- Estimated Effort:
Task B7: Create a reference article for using a kanban in technical writing
- Description: Create a topic-length reference for end usersarticle that includes topic cross-references
- Assigned To:
- Estimated Effort:

C. As a writer, achieve proficiency communicating with a technical audience.

Task C1: Choose a subject area
- Description: Information is needed to document in the subject area
- Assigned To:
- Estimated Effort:
Task C2: Perform an audience analysis
- Description: Identify the goals of an audience (end user, administrator, or developer) and the information that is needed
- Assigned To:
- Estimated Effort:
Task C3: Create an overview article for an audience
- Description: Create a topic-length reference article that includes topic cross-references
- Assigned To:
- Estimated Effort:
Task C4: Create a task article for an audience
- Description: Create a topic-length task article that includes topic cross-references
- Assigned To:
- Estimated Effort:
Task C5: Create a reference article for an audience
- Description: Create a topic-length reference article that includes topic cross-references
- Assigned To:
- Estimated Effort:

Agile Documentation Kanban Board

BACKLOG	PLANNED	IN PROGRESS	REVIEW	COMPLETE
B. As a writer, achieve proficiency with information design principles.	A. As a project manager, manage kanban workflow.
C. As a writer, achieve proficiency communicating with a technical audience.	Task A1 Define user stories and related tasks Assigned To Estimated Effort: Deadline: Notes:
	Task A2: Define criteria for Backlog, Planned, In-Progress, Review, and Complete stages Assigned To Estimated Effort: Deadline: Notes:
	Task A3: Track weekly progress of New, Backlog, Planned, In-Progress, Review user stories and related tasks Assigned ToEstimated Effort: Deadline Notes:

It’s Not What You Say, But How You Say It

joeaseo — Fri, 04 Sep 2020 21:27:49 +0000

I recall contributing to the documentation of an open source collaboration, and I didn’t get any feedback on the articles that I posted to the community wiki. But, just for argument’s sake, I do get comments from users just after I start a review draft of the product documentation (which are based on the wiki articles). Do I incorporate the user comments as part of the product documentation as I would review feedback from the project team? Or should I just collect the user comments and have the product team review them for completeness and accuracy (as is done with bug reports)?

In other words, should blog posts on an open source project be considered as complete and accurate when the product documentation is available separately? Or, more to the point, can a blog replace the need for separate product documentation?

My experience working on open source documentation projects is that, while blogs are a valuable opportunity to solicit feedback, they cannot replace the need for dedicated writers to create the required task, reference, and conceptual documentation. In other words, someone has to bake the cake before others can get a taste.

Perhaps the ideal role that blog posts and community wikis can play will be to provide a forum to discuss how to fill the gaps in the product documentation over the life of the product, perhaps starting with planning and deployment issues (at the beginning of the product lifecycle) to upgrade and migration issues (when the next product release is available).

If a Tree Falls in the Forest

joeaseo — Fri, 04 Sep 2020 21:26:38 +0000

Acting as a contributor on the documentation of an open source collaboration, I recall having issues my issues with blogging to arouse user interest in an early draft of an article). So…after a full month of revisions incorporating feedback from the project team after first posting my article to the wiki, I think the content is now “complete” (or at least it incorporates everything that everyone on the team can think of). Then comes the deafening silence of no responses from the community…kind of like that saying “If a tree falls in the forest, and no one is around to hear it, does it make a sound?”

At first, I’m more than a little discouraged, because community wikis (such as the Liferay Community Edition) are supposed to be this wave of the future that will bring about the age of collaborative documentation and forever break down the walls between professional technical communicators and the user community

But perhaps I’m just being skeptical–it took 20 years before desktop publishing moved from the realm of graphic designers to everyday users. Things take time, and good ideas like wikis will eventually move from the realm of computer geeks to everyday users.

So, I guess I’ll just continue to keep posting articles, being well aware that community feedback may be slow in coming (if at all at first). But if you plant a seed, and the seed grows up to be a tree, then someday that tree just might make a “boom” and someone will be around to hear the sound.

Not Ready for Prime Time

joeaseo — Fri, 04 Sep 2020 20:45:50 +0000

I recall acting as a contributor to the documentation of an open source collaborationt. My initial assignment was to posti an early draft of an article that is barely more than topic sentences with no real detail. Then I get the edict to post a blog to the community to encourage feedback. I thought my blog was pretty innocuous, until one of the project engineers and the engineering manager realize that I’m blogging about features that really aren’t ready, and that the community would have little interest in providing input and feedback. So, after I had (unsuccessfully) spent two weeks of asking the engineers for feedback on the article before I first posted, I managed to get enough additional detail to post a revised draft that may have enough content to actually pique the interest of the community and actually get feedback.

So, the process of collaborating with the community on open source documentation is somewhat hindered by the fact that evangelism of the community often occurs at the same time (to drum up support). It seems to me like a situation of putting the horse before the cart. You may just need stable software builds (with real features) before you can write articles that you can circulate to the community for comment.

I guess the devil is in the details.

Picking Up the Pieces

joeaseo — Sat, 18 Jan 2020 13:01:43 +0000

I completed a writing assignment for a small startup where I revamped the approach to product documentation to emphasize short article-length documents that are preferred for posting to the Web (as if anyone really read book-oriented PDF documents cover to cover anyway).

The company did not make any revisions to the existing product documentation in over a year (and plans for a new product release real soon now). It’s the same startup where I spoke to the engineering manager about the use of open source authoring tools (see my post Bottom Line). The discussion eventually evolved into my proposal to use open source software as a “free” (or at least low-cost) alternative to the expensive per-user licensing and support contracts that are required for commercial tools such as FrameMaker and RoboHelp. In a time when companies want to get the biggest “bang for the buck”, OpenOffice (or variants such as LibreOfice) may be all that a small to medium sized company needs to create short article-length documents that are preferred for posting to the Web.

So, I started the project with no source files for the documentation that shipped with the last software release, no clear idea of which versions of the authoring tools were used, and no real incentive to spend the $999 for the current version of RoboHelp or FrameMaker. My first real task was to take the last available FrameMaker source documents archived from an older software release, buy a compatibile version of FrameMaker, and eventually export RTF files that could be used with OpenOffice before any updates and revisions could actually be incorporated. Along the way, I contended with authoring tools issues (such as template formatting, conditional text, and PDF export) that are not within the expertise of the average technical writer, and I found that the “free” technical support to be minimal.

I managed to break apart the book-length manuals into smaller chunks approximating a chapter in length and topic organization. I found that OpenOffice provided the flexibility to export the content to the project team to review and update in wiki format (moinmoin is what is used here). I could then take those revisions and updates to create PDF files to post on the company web site, as well as serve as the basis of a browser-based online help set that uses standard HTML tags (framesets) rather than rely on JavaScript or ActiveX controls.

A pleasant benefit of using open-source software is that no expensive upgrade was required in order to extend OpenOffice with the ability to import and export PDF files or to import and export wiki formats (both contributed by community members). The bottom line seems to be that low budget does not necessarily mean low tech.

Bottom Line

joeaseo — Sat, 18 Jan 2020 13:01:27 +0000

I recall a conversation with an engineering manager at a small startup who was interested in finding ways to update the existing product documentation, as well as create documentation for a new product release. What piqued my interest was that the conversation led to a discussion of authoring tools and their ability to handle current output formats such as HTML and PDF, as well as Web 2.0 technologies such as blogs and wikis for collaborative documentation.

Coming from a big company background with dedicated publication teams, it was easy for me to assume that their documents were created using commercial software such as Microsoft Word or Adobe FrameMaker. At first, I argued the relative merits of a word processing tool such as Word for short documents and FrameMaker for multi-chapter documents. Then, I realized the manager was far more interested in the use of open source software such as OpenOffice for authoring.

I continued the discussion comparing the relative merits of OpenOffice against Microsoft Word, when I began to see that the discussion was evolving into the prospective use of open source software as a “free” (or at least low-cost) alternative to the expensive per-user licensing and support contracts that are required for commercial tools such as Word and FrameMaker. In a time when companies want to get the biggest “bang for the buck”, OpenOffice (or variants such as LibreOffice) may be all that a small to medium sized company needs to create the short article-length documents that are preferred for posting to the Web. Even more, open source software such as the Liferay portal application can not only be used to publish content to the Web, but also to manage Microsoft Office formatted documents in a content management system.

Through the collaborative efforts on open source software, the bottom line seems to be that low budget does not necessarily mean low tech.