The document discusses the Dexy documentation tool. It provides 10 ways that Dexy can help with projects, including promoting projects, helping users, improving code quality, getting involved in open source, contributing confidently, expressing yourself, writing productively, keeping documentation current, learning, and earning. It also discusses Dexy techniques like templating, sectioning, JSON, writing filters, using subprocesses, configuring Dexy, running Dexy, and the output. It emphasizes writing the right kind of documentation for the purpose.
3. 1. Promote Your Project
QUICKLY create a website and HTML documentation
including tutorials and reference guides for your project.
4. 2. Help Your Users
Make sure your documentation is CORRECT, easily ITERATE
it based on user feedback, help your users make the most of
your software.
5. 3. Improve Your Game
Write about your code. Writing literate documentation
improves your code. If you can’t explain your code in words,
or if it looks ugly on the page, you need to refactor it.
6. 4. Get Involved
Write about other people’s code. This is the best way to learn
about a new library or language, and contributing
documentation will get your foot in the door.
7. 5. Contribute with Confidence
Nervous about starting to contribute to open source projects?
Explain your patch in words, send this along with your patch.
You’ll feel more confident, and so will the recipient.
8. 6. Express Yourself
Blog about what you do, share your experiences with the rest
of the community. Dexy supports WordPress, Tumblr and
Posterous already and should be able to work with any
blogging API.
9. 7. Write Productively
Dexy helps you write reports and articles QUICKLY, write
source code using your favourite text editor or IDE, pull in
snippets and transcripts, you’ll be amazed at how quickly it
comes together.
10. 8. Keep it Current
Writing your documentation in Dexy makes it easy to
MAINTAIN in the long term. Don’t waste your time writing
documentation that’s going to go out of date.
11. 9. Learn
Keep a coding journal as you learn new languages or
techniques, easily refer back to earlier examples and track
your progress as you learn.
12. 10. Earn
Use Dexy to create marketable content like books, training
courses and consulting reports.
22. Templating
Dynamic documents {{ a[‘first’] }} a way to {{ a[‘second’]}}
dynamic {{ a[‘third’] }}.
a = {‘first’ : ‘need’, ‘second’ : ‘insert’, ‘third’ : ‘data’}
Dexy has support for Jinja2 for now, but more templating
systems will be added.
Probably will be a system of core utilities available to
template systems (e.g. random filename generation).
23. Sectioning
boring boilerplate setup code and imports
### @export “cool-stuff”
really interesting cool stuff
### @export “more-cool-stuff”
even more cool stuff
### @end
boring teardown code
24. JSON
Data written to JSON files is made available as a dict. Great
place to store { ‘mean-of-population’ : 5.5, ‘stdev-of-
population’ : 1.2} for easy {{ a[‘stats-data’][‘mean-of-
population’] }} retrieval later.
26. Writing Filters
Can be as easy as:
def process_text(self, input_text):
# do stuff
return modified_input_text
or as sophisticated as you need.
It’s shockingly easy to do complex things with Dexy filters.
27. Subprocess
Non-Python code is handled using pexpect (linux/mac only).
Working on subprocess() support in Windows.
Windows users encouraged to run Dexy in Linux VM.
33. What documentation?
What kind of documentation you are writing?
Reference documentation is not the same as tutorials.
Developer docs are not the same as user docs.
Please do not document via source code comments.
Dexy makes it easy to write many different kinds of
documentation, reusing the same code snippets if you want,
so take advantage of this.
34. Slides for talk given at OSSBarCamp on 26
September 2010 by Ana Nelson.
Slides are licensed as http://creativecommons.org/licenses/by/3.0/ so feel
free to re-use with attribution.
Visit http://blog.dexy.it for more information, or
contact me ana@ananelson.com
