1  ''' This is not needed but a new guide on how to document on this Wiki
  2  should be added to [Help:editing](Help:editing "wikilink") '''
  3  
  4  1.  Documenting
  5  
  6  Without clear documentation, new members to the community have no clear
  7  instruction on how they can help to make Status better. We truly value
  8  contributions that help to improve our documentation; whether that be
  9  tutorials for users, additions to the FAQs, or more granular
 10  instructions for developers - it all adds up and our community
 11  appreciates it :)
 12  
 13  Our Wiki is powered by MKDocs, and is on:
 14  [1](https://github.com/status-im/wiki.status.im)(https://github.com/status-im/wiki.status.im),
 15  and if you spot any errors, find parts of the documentation confusing,
 16  or have some suggestions on how we could have clearer communication we'd
 17  love your help, and feel free to let us know via the \[Status
 18  Slack\](http://slack.status.im).
 19  
 20  1.  1.  Documenting Guide
 21  
 22  It's fairly difficult to write a general documentation guide as how you
 23  document stuff will depend on what it is you are trying to explain. The
 24  most basic stuff to know is that MKDocs uses markdown as it's primary
 25  language, although you can also write your guides using inline HTML as
 26  well. Please go
 27  \[here\](http://www.mkdocs.org/user-guide/writing-your-docs/) for more
 28  detailed info on this, as well as a look at how the file structure of
 29  our docs works.
 30  
 31  1.  1.  Getting Set Up
 32  
 33  You need to have both python and pip set up on your machine to install
 34  MKDocs. You can find all the information for how to do that and what
 35  versions are required \[here\](http://www.mkdocs.org/). I had python
 36  already installed on my machine, but needed to get pip:
 37  
 38  \`\`\` sudo easy_install pip sudo pip install mkdocs \`\`\`
 39  
 40  It seemed like using \`sudo\` was important otherwise the mkdocs install
 41  failed with some nasty stack trace, but that may have been specific to
 42  my environment (Mac). Once you have got that all working and
 43  
 44  \`mkdocs --version\`
 45  
 46  returns an answer (currently \`mkdocs, version 0.16.1\`), then you can
 47  clone into the status repo and get going.
 48  
 49  \`git clone <https://github.com/status-im/wiki.status.im.git>\`
 50  
 51  (or \`git clone git@github.com:status-im/wiki.status.im.git\` if you
 52  have your SSH keys set up) followed by
 53  
 54  \`\`\` cd wiki.status.im mkdocs serve \`\`\`
 55  
 56  You should then be able to navigate to <http://localhost:8000> or
 57  <http://127.0.0.1:8000> and see the changes you are making to the wiki
 58  as you make them. Magic\!
 59  
 60  1.  1.  General Notes on What We Look For
 61  
 62  Generally speaking, we like a lot of screenshots and less language as
 63  this helps us to guide people all over the world who may not all speak
 64  the same languages. Take a look at our \[User
 65  Guide\](http://wiki.status.im/getting-started/user-guide/) for a rough
 66  outline of what we mean by balancing your text with screenshots and
 67  other helpful images.
 68  
 69  As you can see from our \[github
 70  repo\](https://github.com/status-im/wiki.status.im) all of the different
 71  documents are kept in the \`docs\` directory. Click through to there to
 72  find the section and then the specific document you are wanting to add
 73  to or edit, or make a new file for documentation that you feel is
 74  missing.
 75  
 76  <center>
 77  
 78  <img src="../img/status-wiki.png" />
 79  
 80  </center>
 81  
 82  In the top level repo, you can also see an \`mkdocs.yml\` file, which is
 83  what controls how and where each document appears. If you are adding a
 84  new document, you will need to speak to Jarrad, Carl or another team
 85  member to figure out where it belongs, but either way you will need to
 86  edit this file in order for it to appear. It is definitely best to
 87  communicate with the core team before diving this deep though.
 88  
 89  As you can see, I have uploaded a bunch of images into this post (which
 90  is largely about encouraging you to use lots of images in your own
 91  documentation and explainers). The images are all kept in the \`img\`
 92  directory in each folder within the \`docs\` directory. You cannot
 93  upload straight to these \`img\` folders as that requires push access to
 94  the whole repo, but you can make your own fork of \`wiki.status.im\` and
 95  upload the images there to be merged by the team once you have completed
 96  your awesome work. To do all this, navigate to the folder you are
 97  working in and click the \`Fork\` option in the very top right. This
 98  will start a new fork of the wiki in your own repo, where you can upload
 99  the photos and then later push back to status to be merged.
100  
101  <center>
102  
103  <img src="../img/img-location.png" />
104  
105  </center>
106  
107  Once you have forked it and selected where it should go in your profile,
108  you can then add images easily by either dragging and dropping or
109  uploading directly from your machine.
110  
111  <center>
112  
113  <img src="../img/forking-repo.png" />
114  
115  </center>
116  
117  You can select the first radio button option to commit the uploaded
118  images you need directly onto your own master branch. From there, once
119  you are sure that all the changes you have made are the ones you want to
120  make and look good on the wiki via that neat trick with
121  
122  \`mkdocs serve\`
123  
124  then you can submit a PR to the actual status wiki:
125  
126  <center>
127  
128  <img src="../img/pull-request.png" />
129  
130  </center>
131  
132  Click the highlighted button near the top right and follow the
133  instructions from there to submit your changes to the status team. You
134  should see a screen something like this where you can review all the
135  changes you have made before actually submitting. For the PR, I have
136  uploaded the photos needed for this post, made two grammatical changes
137  to the User Guide and, obviously enough, uploaded this entire
138  \`documenting.md\` file, all of which I can review easily.
139  
140  <center>
141  
142  <img src="../img/comparing-pr.png" />
143  
144  </center>
145  
146  Thank you so much for adding to our wonderful, free (libre) open source,
147  community-driven effort to bring Ethereum to the people\!
148  
149  1.  1.  Documentation Guidelines
150  
151  These will evolve as the project does, but really depends on what
152  specific type of documentation you are looking to help out with. For
153  technical documentation, examples and lots of code is what we are
154  primarily looking for; by way of example see the first set up section of
155  this article. For instance, in order to add an image here, you can
156  either use inline html (my preferred option because it is easier to
157  position and style) or the normal markdown way of doing things. The
158  images above are inserted like so:
159  
160  \`
161  
162  <center>
163  
164  <img src="../img/status-wiki.png" />
165  
166  </center>
167  
168  \`
169  
170  and style tags etc can be added really easily:
171  
172  \`
173  
174  <center>
175  
176  <img src="../img/status-wiki.png" style="width:300px" />
177  
178  </center>
179  
180  \`
181  
182  or you can just do it in normal markdown:
183  
184  \`\[\!\[We lost the documentation on quantum mechanics. You'll have to
185  decode the regexes yourself.\](img/xkcd-224.jpg)\](https://xkcd.com/224/
186  "We lost the documentation on quantum mechanics. You'll have to decode
187  the regexes yourself.")\`
188  
189  If you are writing documentation that is end-user-facing, rather than
190  aimed at the technical folks in our community, then the less code and
191  text and the more pretty images with directions scrawled across them the
192  better.