We have decided to stop the maintenance of this public GitHub repository.
The answer is, we do. We care about your documentation. We are a team of technical writers and editors at SAP Hybris with a lot of experience documenting REST APIs and other solutions surrounding that topic. We came up with a way to ensure your docs are tops! We provide the following:
- Guidelines and requirements on how to properly document your project, located right here in the repository.
- Mentors who provide expert writing tips for non-native English writers, and anyone who needs a little help in the writing department. Tips are located on the wiki tab in GitHub.
Here's a suggested path, with some helpful waypoints for your journey through the guidelines.
-
The best place to get your feet wet is the Table of Contents. It quickly outlines the different types of guidelines, and the requirements for certain documents. After a quick review of the Definition of done, jump right in and learn the best writing practices. For instance, write in active voice, present tense, and second person. The Style and standards section also guides you on topics such as how to effectively use certain terminology, and voice and tone.
-
Don’t worry about how to format your code, because the Syntax Guidelines explain when to use bold font and when to use code font, with plenty of examples. Also learn how to use popular technical writing techniques such as lists, tables, links, and images in your documentation.
-
The REST API Documents section provides all the fine-grained details for what type of documents are required for your API, and why. This section also breaks down how to write a proper release note to keep users updated, but also how to use it to promote your product.
-
The More Documentation section provides the guidelines for any other type of documentation, such as a Solution or README file.
What is WaaS? It stands for Writing as a Service, and the WaaS blogs aim to mentor and provide expert advice for how to write the best tech docs out there.
After you start writing documentation, you undoubtedly want to learn more writing tips because you care about the quality of your docs. That’s when you should hop on over to the wiki tab. See real examples in action, such as how to turn a confusing, passive sentence into a clear, concise sentence by using active voice. That’s just one example. The tips go on and on.
Every detail is explained in our blog posts and webinars. You can become your own technical writing expert, and in turn, teach your peers and others around you the tips that you learn.