This content has been moved to the documentation repo https://github.com/decentraland/documentation
The goal of this repository is to feed the Technical Documentation site with technical tutorials on various subjects related to the Decentraland Platform and Protocol to help the community understand how things work and build new projects on top of it.
The following section is intended to be a guide with some key points and structure to take into consideration when writing a technical document. This can be handy when starting from scratch and not having much experience in writing:
-
Start with an Introduction:
What will the reader learn? What skills will the reader need? What problem does this article helps solve? -
Add gists with code snippets or required configurations to ease the execution of the tutorial. Remember to add formatting and folder structure where files belong and make the code as digestible as possible. Remember, instead of doing what's easy for you, do what's easy for your reader.
-
Know your audience, try to avoid acronyms and add links to glossaries or referenced concepts so that people can drill down if needed. Always use the clearest, simplest language that will do the job.
-
Conclusion: close up the learning and what you have covered.
-
The focus of the tutorial should be “how do I accomplish X”, the main content should all be actionable and to the point. Don’t go off on tangents explaining everything.
-
Any useful clarifications can be made as notes. Notes are great to add optional content that gives context but that users can ignore if they’re in a hurry. It should be easy to tell notes appart from the required reading.
Check some other technical writing guidance, Amazon has some good Blogposts and tips to help you improve your writing.
The Technical Documentation site is generated by scrapping the /docs
folder of different repositories. To add a new tutorial, just create the file under /docs/tutorials
and add a reference to that file in the index.
As of today (June 2022), the publication of the Technical Documentation Site is done when there is a merge in its repository, so to see your documents live you may need to manually trigger the build processes.