Chapter 9

Chapter 9 in Software Development: An Open Source Approach focuses on user support and why it is such an integral part of software development. It continues by describing four types of user documentation: on-line help, reference manuals, open discussion forums, and tutorials. This documentation is usually in the form of technical writing which the chapter discusses further.  The principles of good technical writing are organization, illustration, style, and tone while being–most importantly–clear and simple. According to the text, there are a few guidelines to enforce these principles:

1. Write a logical outline.
2. Put summary information first.
3. Use the language of the domain.
4. Be precise.
5. Use the present tense.
6. Be direct.
7. Be concise.
8. Use simple and short sentence structure.
9. Use parallel sentence construction.
10. Use the active voice.
11. Use positive terms.
12. Punctuate properly.
13. Check your spelling.
14. Use computer terms.
15. Avoid specifying gender.
16. Clarify acronyms and abbreviations.
17. Avoid slang and jargon.
18. Avoid weak verbs.
19. Write cohesive paragraphs.
20. Use two columns.
21. Use short numbered lists.
22. Add a graphics.

The user is an important part of the software engineering process, and therefore it is crucial that user support is able to resolve issues as they arise.

---

 

9.1 Read the written user documentation for the software project on which you are working.

a. Write a brief critique of that documentation vis-a-vis the principles of good writing introduced in this chapter.

Gephi’s documentation is not the best. What little there is on their GitHub’s wiki is often outdated or lacking in one way or another. Their greatest downfall, however, is their lack of graphics. Particularly with tutorials, it’s the images that aid most efficiently. Effective graphics provide users with a kind of understanding that words sometimes can’t. This is exactly the reason why our team included several graphics (screenshots of each step) within our rewritten “Build” documentation on Gephi’s wiki.

b. Briefly characterize the wider audience of people who use the software produced by your project. Include in your characterization factors like reading level, cognitive skills, native language, and education level.

Users of Gephi are generally expected to be intelligent, data seeking individuals. From what I can tell, most work in fields such as biology, data analytics, and mathematics where a higher education is required.

c. Evaluate the quality of your project’s written documentation with respect to how well it matches the characteristics of its wider audience of users.

I think Gephi definitely has some room to grow in terms of documentation for the user. While there are example graphs, there isn’t much text explaining the functionality and capabilities  of the functions.