Skip to content

Writing the guide in README.adoc

Jump to bottom
Laura Cowen edited this page Dec 1, 2017 · 1 revision

There’s a template.adoc file in the guides-common repo.

See template.html for guidance on using the template.

  1. Think about the audience for your guide. They are Enterprise Java developers but what specific skills do you expect them to have to be able to complete your guide?

    • Is your guide an introduction to the technology? If it isn’t an introductory guide, you can assume they have done the introductory guide already and not duplicate it (make sure there’s a link to it in the standard way - TBD).

    • ?

  2. Based on that, sketch out at a high level what you need to cover in the guide. What do you need to instruct the user to do to aid their learning about this particular topic? What is irrelevant or just padding?

    • Don’t make the user build the whole sample application because at least some of it is probably irrelevant to the focus topic of the guide.

    • For example, if the guide is on creating a RESTful web service, only mention the bits of the pom.xml that are relevant to learning about creating a RESTful web service. And don’t go into too much details about the pom.xml because the user isn’t there to learn about writing Maven POMs. Instead, provide the pom.xml file in the start directory for the application to use.

    • Minimise the number of sections you include. Break the guide down into meaningful sections but try to avoid adding more than 2-3 sections beyond the standard sections provided in the template.

    • If you do find that you need to add a lot more sections and sub-sections, consider whether you need to cover all the detail that you are providing and whether it is all relevant to this guide.

    • Don’t try to include everything. Keep the guide as short as possible.

  3. Write a draft of the guide. *

    • Remove everything that isn’t directly relevant to the focus of the guide. If you’re not sure, it probably should be removed. Try leaving it for a few days, if you can, and then come back to it fresh.

Other things:

  • When describing an upcoming code snippet, end the lead-in sentence with a colon (:). This makes clear the connection between the sentence and the snippet. For example:

Clone this wiki locally