| tags | projects |
|---|---|
In reference documentation frequently we need to explain a concept or convey an idea before going into details. This is similar to the way a presentation may provide additional background. Reference documentation however is used repeatedly so it needs to remain focused, factual, and complete. It is not a good place for conveying ideas that only need to be conveyed once. More importantly conceptual information most likely ends up in side notes and overviews where the topic is most likely not adequately covered. The problem is only multiplied with time as new authors consider where to add or expand on existing information.
A good solution is to create topical guides separate from reference documentation. The purpose of this repository is to hold such topical guides for Spring projects. The repository is shared across projects since ideas and concepts, more so than reference documentation, tend to apply across projects and remain valid across versions.
Consider the following guidelines:
-
Cover a topic specific to Spring projects.
-
Communicate big picture ideas, not low level details.
-
Use code samples to convey ideas, not to accomplish a task.
-
Think beyond individual projects.
-
Make few assumptions about prior knowledge.
-
Make it easy to follow and read in 15-30 min.
-
Suited for phone or tablet with no IDE.
A good topical guide is like a Youtube intro video, a lightning talk, or a StackOverflow thread. The tone is vivid. It speaks directly to users to communicate concepts. The opening paragraph should identify the motivation for the guide, why it matters and who the target audience is.
In relation to getting started guides, readers might first check out a topical guide to get oriented, then follow getting started guides to accomplish specific tasks. Or they might start with a getting started guide and find that they need more colour on a specific topic, to understand how the code in the guide actually works, or can be customized.
|
Note
|
there are also some micro-guides called
"understanding" guides
in spring-guides. These are really short, one or two paragraphs at
most, and can easily be distinguished from topical guides by their
length and limited scope.
|
Each guide has an id, title and description that allow it to be
located in the main website. The id is the project name with the
"top-" prefix stripped off. The title and description are scraped from the github repository description in the form <title>::<description>. Look at some existing guides to see how that works, e.g. Spring Security Architecture.
In addition, a guide can have tags, and related projects. A tag is an arbitrary word (like "security"). A related project is a Spring project ID from the website (e.g. "spring-framework" or "spring-cloud-netflix"). You can specify these forms of metadata in a special header in the form of a YAML document (like with Jekyll). See the top of the source code for this page for an example.
You should probably also add :toc: at the top of your document, to ensure that a table of contents is rendered.
Clone this repository and edit the README to contain the content of your guide. Currently we can only support guides in Asciidoctor[http://asciidoctor.org/] but Markdown[https://guides.github.com/features/mastering-markdown/] support is planned. Add images, code, etc. directly in your fork. You are encouraged to use advanced features of Asciidoctor if you need them (like includes, admonitions, etc.) If you use relative paths you should get a good idea of how it will render by simply browsing your fork in Github. If you use absolute paths for includes, they will be processed in the final markup on the website, but Github will not render them for you.
When your content is ready for review, send a pull request and explain why the topic is needed and how it fits in with other guides if there are any that are relevant.