Having good documentation is central to any cryptocurrency project since the subject can be confusing to users, and it is important for users to have a reliable set of up-to-date examples for common configurations and questions. Documentation, like the marketing and community management, is an ongoing process that serves to make Decred more tangible and accessible to users. We are looking for a few contractors to expand and maintain the existing documentation for Decred. These positions will be staffed from within the community, and once the work is parceled up, contracts will be prepared. There are a number of areas in need of maintenance or building out: - update and add to text and image documentation on docs.decred.org - audit external linking to docs.decred.org - add narrated screen capture videos for the most common configurations - review forum content to find new content to document on docs.decred.org - participate in an update of the documentation site design - keep existing content up-to-date as the software changes If you're interested in working on documentation or if you think there is some key area that I missed in the above list, please reply in this thread and tell us about it.
I am interested in helping out with some of these needs. Please message me so I can get a bit more info on time / work load requirements / length of contract and such.
Here are my thoughts/notes from having reviewed and worked on the docs. General Improvements Need to define the target audience. Is it written for people new to cryptocurrency or for people who are familiar with Bitcoin concepts? There are definitely assumptions of knowledge/familiarity sprinkled everywhere. There is little reason to have Windows/Linux/Mac specific pages. You download/extract/run/install/adjust configs the same on each platform. The commands and paths are just slightly different. It should be a single document and each step should have examples for each. All the information being broken across various sections and subsections makes it really hard to follow. A single long form page that has good logical/linear progression might work better. Right now it requires a lot of going back and forth between different pages. Getting Started This needs a big update which is obvious to anyone who has recently tried to follow the directions as they are written. There is no mention of Paymetheus here at all. PoS Mining This was last touched when dcrticketbuyer was new. Now that is kind of going away as the functionality is being merged into dcrwallet. Might be better to wait until 0.8.0 since more changes have happened since 0.7.0. There really needs to be an 'Advanced PoS Mining' section. The current documentation kind of glosses over all the factors at play. PoW Mining The solo mining portion isn't linked because it needed to be overhauled. Should be updated to focus on gominer since that's all that is actively supported. Other Thoughts The documentation should state what version(s) of the software it applies to. It'd be nice to have simple upgrade notes for each release. This is sort of done in the development dispatches but they are typically incomplete.
Along these same lines, I have thought for a long time that while the development dispatches are nice for programmer types actively following development, I honestly think they are not very useful for the general community. I would really rather see a community member that handles documentation translate them into more tangible user-facing release notes. For example, let's look at just the first few lines of the 0.7.0 development dispatch from a user perspective: What implications does any of that have for me? Do I need to do something differently? Should I be changing settings? What happens if I don't upgrade? What benefits do these bring me? Why do I care that you updated your dependencies since I just run a binary? What is Sp and how does that affect me? Ummm block notificaller what?
I was planning on writing up the release notes for future releases, but having someone who maintains the doco do this in the future is totally an option. Reducing the DDs into user-tangible parts is planned for releases from 0.8.0 onwards.
Perhaps keep all the stuff in (at the end) but preface it with Dave's suggested intro paragraph/brief summary of update(s).
I'll put my hand up for this since I wrote a lot of it in the first place. I agree that it's time for a bit of an overhaul. A lot has changed in the months since it was written. I can also do the technical translation since that's part of my full time job (I'm a developer for an agricultural simulator and also run the training courses). I never got around to doing the Golden Path (a linked walk through of the main information a new user will need) so it would be good to get into that. We need an easy way of proving basic information to non-technical users. How do I get started? How do I transfer funds? And of course, new documentation that promotes and show cases the GUI wallet and tools.
As the person who has been writing the current dev dispatches, I can chime in here. Getting the release notes ready (and other release things) is a lot of work so even if I wanted to I don't think I'd be able to write up a higher-level/user change document. The current dev dispatch is really just a minor retooling of the release notes (which I do think are important). That said I'd be thrilled to work with anyone who wants to get that ready before each release starting from the release notes or dev dispatch. Since we have multiple projects it is hard to keep track of exactly what interesting things go into each release for each project. For example, I can generally tell you exactly what has gone in to decrediton and gominer but I have almost no idea what happened in Paymetheus beyond telling you the PRs that went in. So a better doc probably depends on both looking at the PRs lists I make and talking to someone who worked on each component when it isn't clear.
I see you submitted a PR for dcrdocs a couple days ago, thanks for submitting that. If you're up for more documentation work, we would like to have you do it under contract.
@Shadowlance, good to see you've retained your interest in generating documentation from RFP-0004. We would be happy to have you continue your work from earlier in 2016 on an ongoing basis.
My wishilist for docs.decred.org: Please do not (ab)use web fonts for non-text, like icons. I disable web fonts for better security. Please make navigation possible without javascript. docs vs wiki. I found some content on wiki.decred.org as well. I guess docs and wiki have different purpose. But just in case, if they overlap there is a danger of content duplication or knowledge scattering, for example Schnorr Signatures vs Schnorr-Based Elliptic Curve Cryptography. Personally I much prefer the Git-based docs over MediaWiki-based wiki. I can get the whole thing for offline reading and it is more censorship resistant -- it's harder to "take down" a Git repository when it was cloned by many people. P.S. I deally I wish all decred websites are usable without web fonts and javascript, but for docs this is more important imho.
I'm not a fan of javascript either. I'd also like to see these things happen. Something we should discuss after we get all of the updates to the documentation written.
We'll do what we can. We're constrained by the document server (mkdocs) as far as javascript goes but we can look into a no-javascript option if one exists. Same with web fonts. I'm not a web designer and all the copy is in markdown so it's whatever mkdocs uses. I do agree that the docs should be as clean and simple as possible and that's a goal we're trying to keep in mind. As for the wiki, it's up to the dev team (or maybe a stake vote in the future?) as to whether or not we keep it. In my experience, technical wikis are usually only updated by devs or people like me with an express interest in documentation. I'd prefer to keep everything on github and thus on docs.decred.org. Anyone can make a pull request on the docs anyway so it's almost like a wiki. Not sure we need the separate one. At any rate, it'll stay until we can migrate all the technical info over and we can decide once that's done.
As I said in the github issue, I think we should get rid of the wiki. I'm normally a big fan of wikis for docs but at this point the docs site has gone much further and keeping the two in sync will never work out.
Could be theme issue. Vcash wiki also uses MkDocs but has all links available on the side. It still abuses web fonts though. Talking about navigation structure, I liked Python docs. Note how all links are clearly exposed, and not hidden behind hover menus (which are poor UX for e.g. touch devices, even if done in pure CSS).
We have a design update to the dcrdocs site prepared for the 0.8.0 release, and it uses the vertical nav bar instead of the horizontal one. Last I checked, it doesn't require JS.
Not to downplay your security concerns at all, but I am almost certain that our documentation website was built in a way to avoid any and all 3rd party resources, so even those web fonts should be coming from us (if this isn't the case, be loud about it, because that wasn't the intention). I also think that there is a way in modern html (not a web dev myself, but I've seen this on some blogs) where we can provide a hash of a 3rd party resource in our html and the browser will only load it if the hash matches. That is another way to prevent unintended/unauthorized loading of 3rd party resources, but if we self host everything anyways, it shouldn't matter.
I understand those concerns regarding too much fancy javascript. As far as i have put my head into mkdocs it is build on the twitter.bootstrap which comes with several js and css files. This setup is the standart templating system implemented in the go.source and those default .css and .js files got served from github or another place. When you edit those .css files locally those changes won't appear on the website. The only file that was editable trough the filesystem was the style.css to create a custom template. All other things how the page html gets rendered have to be edited in the source code which makes it more or less pain in the ass, but i didn't looked into it specificaly. There are also two 3rd party files included like fontawesome and mathjax.js. They are linked to 3rd party resources in the sourcecode head and foot, that should be changed.