ow2 technology council oscar quality programme … software documentation best practices ow2...
TRANSCRIPT
Open-Source Software DocumentationBest Practices
OW2 Technology CouncilOscar Quality Programme
oscar.ow2.org
Preliminary Remarks
“Documentation can't be an afterthought – it needs to be part of the release process.”
Source: 10 tips for better documentationPaul Adams, director of engineering at KDAB
3
Reading the documentation is how users and developers will get one of their first impressions about your project. They will infer much about the project’s quality itself from their experience with the documentation.
Examples of Outstanding Project Documentations
Nuxeo doc.nuxeo.comOpenStack docs.openstack.orgEclipse help.eclipse.orgDocker docs.docker.comOW2 projects:
Proactive Workflows & Scheduling BonitaWebLabHammrCollab projects: XLCloud / Choreos
4
Key Recommended Features
Attractive home page with nice layout
Common formatting across sections
Outline for easy navigation
Syntax highlighting
Screenshots
Search
Glossary
Accessibility
5
Before Writing…
Before writing, ask yourself:
“Why do my readers need this content? This question is probably the trickiest of all, because it puts the purpose of your content under scrutiny with the WIIFM (what's in it for me) test: Why are you even writing this content? Which pain are you solving for your readers? Why would they care about what you're writing? Lots of hard questions to answer, I know.”
Source: Content strategy: the new philosophy of technical documentation – Mikey Ariel, RedHat
6
Documentation Types
1. Getting started2. Installation and administration guide3. User guide4. Developer guide5. API documentation6. Code documentation7. Tutorials / cookbooks / recipes
8
1/7 Getting Started or README Documentation
It is the strict minimumMust have sections:
Project’s featuresRequirements and installationSupportLicense
9
NB: “All this has to be written for someone who never heard of your project before, and may never even have considered something like your project. If you’ve got a module that calculates Levenshtein distance, don’t assume that everyone reading your README knows what that is. Explain that the Levenshtein distance is used to compare differences between strings, and link to more detailed explanation for someone who wants to explore its uses” Source: 13 Things people hate about your open-source software docs
Example: erocci
2/7 Installation and Administration Guide
Purpose: provide guidance on the software installation and on its configurationRecommended sections:
RequirementsInstallation stepsSystem configurationSystem monitoringPerformance tuning Troubleshooting
10
Example: XWiki
3/7 User Guide
Purpose: present the software goals and usage in greater detailsRecommended sections:
Table of content
One section per main function
Screenshots
FAQ
Links towards further help
11
Example: Lutece
4/7 Developer GuidePurpose: facilitate developer contributionRecommended sections:
Getting the code
Build instructions
Architecture with diagrams
Issue tracking + easy bugs
Coding conventions
Patch submission
Testing process
Translation process12
Example: WebLab developer guide
5/7 API Documentation
REST APIs: list all end points
Provide sample code
Consider API description languages: Swagger, Raml, JSON Hypermedia
Use an efficient UX
13
Example: ProActive Workflows & Scheduling
6/7 Code Documentation
14
Code artefact naming is documentation
Use consistent naming rules
Documentation tells what you are doing, code shows how you are doing it and comments explain why you are doing it this way
Reference issues
7/7 Tutorials, Cookbook, Recipes
15
Purpose: help solve specific problems and reduce the learning curveBest practices:
Use several formats to address different learning profiles: code recipes, videos, slides, …
Promote community materialExample: SpagoBI
Tutorials
Enterprise scriptable wikiLGPL v2, Java10+ years project and companyXWiki SAS OW2 corporate memberKey features for documentation:
Collaborative editingContent versioningSyntax formattingTable of contentDocument inclusion supportUML diagramming extensionsInternationalizationPDF export
Recommended Solution for Writing Documentation: XWiki
17
XWiki.org
Tools for API documentation, diagrams, a11y, …
REST API documentation generation: Swagger, MiredotDoc and UML diagrams generation:
Doxygen
Forums: discourse.orgAccessibility check: AsqatasunIssue tracker for keeping track of documentation related issuesAlternative writing tools: Corilla, Sphinx
18
Collaborative Project Documentation How-To
Create a dedicated space in the project’s public wikiRequest the creation of a dedicated navigation panelYour contacts at OW2:
Olivier Bouzereau, community coordinator
Olivier Lizounat, webmasterStéphane Laurière, CTOReach OW2 also via your project’s JIRA
19
ResourcesArticles and guides
Doc-dish articles on opensource.com
Oscar wiki – Documentation section
Publication / Dissemination
FLOSS Manuals.net
Community events
Write the Docs
Open Help
20
Open-source Software DocumentationBest Practices
Thank youoscar.ow2.org
22