Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I need a personal archive tool to archive the programming algorithms, lessons, techniques and codes.
Something like a "Personal Wiki" that supports images attachments, code decoration, content categorization and search for any content at any time.
I know i can use an open source tool like forums or media wiki but i need something customized for this personal purpose.
Desktop tool or web tool.
For those who are search for the same purpose, I found some tools:
Here are some things I've tried with their pros and cons:
OneNote
Pros
Excellent ability to organise notes. You have have books containing section groups containing sections containing pages and subpages. I've got a book for Development, then a section group for Languages, then a section for Ruby, then pages for every topic within Ruby. The highlight here is that there's no penalty to creating dozens and dozens of pages on a given topic, helping you keep things organised when you get really deep into a specific topic. It's an easy mistake to just say "Yeah, a section for Languages, then a page for PHP", but before you know it the PHP page is half a mile long and you'll never sit down to properly re-read it again, it becomes a pain to find the info you want, etc.
Great support for multi-user notebooks. It properly keeps track of who added what and what got changed when, making co-operation easy.
Syntax highlighting can be done with the OneTastic plugin, which lets you define custom styles. Just define a custom style in a monospaced font with a special colour, and call it Code.
Support for tabular data, attached files, audio, video, etc, if you need that sort of thing.
Cons
Need to use a special app to consult it, so you can't just hit it from a work computer or the like.
Web app is clunky and lacking full features, I still haven't gotten a desktop notebook to properly sync as a web app notebook.
Search isn't the best.
MediaWiki
Pros
If you make it public, you can use Google on your notes, which is better than any other search.
CSS means it's easy to style and present it how you want without manually altering every bit of text like you'd need to in OneNote.
Because it's just a website like any other, you can access it from any device without installing anything or having to log in.
Export as ePub file, meaning you can read all your notes on your Kindle/ereader, really good for refreshing.
Any page can belong to multiple categories, which is nice.
Built in syntax highlighting with code tags.
Cons
Limited/clunky ability to organise in tiers, ultimately a fatal flaw for me.
Becomes a pain to quickly add notes to pages. (I would kill for a no-page-reload transition between read/edit modes!)
Reliant on an internet connection (usually not a problem, but something to be aware of).
Plaintext files in folders
Pros
Zero learning curve/adaptation.
Read them anywhere with no special software (tip: put them in a shared Dropbox folder, map an address on your domain to that folder).
Read natively on ereaders or convert to ebook format with no real effort.
Cons
No syntax highlighting, no image/audio/video media, no tabular data.
Hard to fuzzy search.
Edit conflicts if you're studying alongside someone.
Google Drive
Pros
Excellent support for sharing/co-operation
Good search
Good mobile support
Supports a lot of media
Cons
Tends to be slow to use
Presentation options tend to be frustrating
Reliant on internet connection
My personal recommendation: OneNote + Onetastic plugin, using all tiers/dividers, exported to PDF or multiple PDFs regularly so you can consult them from elsewhere.
Quoted from this link:
https://www.reddit.com/r/learnprogramming/comments/3acusr/how_to_take_notes_while_learning_programming/
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm the author of a fairly sized (and growing) framework. It primarily exposes JavaScript APIs, but also has public APIs in Ruby and a growing CoffeeScript segment. (CoffeeScript will eventually encompass most of the project, but there will always be a significant pure-JavaScript presence.)
Up until now, I've been documenting the JavaScript with PDoc and the Ruby with RDoc. Though I've no issues with RDoc, unfortunately PDoc is aging, high-maintenance, and requires a heck of a lot of typing that feels like superfluous clutter. Also, the transition of most of the code to CoffeeScript renders PDoc much less useful than it was.
Example of the project's current documentation
I've experimented with Rocco in a local branch and it works better than I expected. What's really nice is that it works with all my code, from Ruby to Coffee to JS. It's nice to see all the documentation in one place. It's kind of cool to see the source code next to the documentation, too, and this makes it very clear what a particular code segment is actually doing.
However, I am a bit worried about the overall structure. Docco/Rocco seems great for niche projects with very few public APIs, but its read-the-entire-project style strikes me as a double-edged sword. Though it's very informative, having to vertically scroll through the files without even a table of contents (not to mention, knowing which file to go to in the first place!) seems like it would make it difficult to actually find anything. Also, the default template required some hacking because the list of files was too long to be displayed. Not a huge deal but an annoyance, and a hint that this project may be out of Rocco's league.
I'm now considering CoffeeDoc. Judging just by the example, it seems promising, but it is of course Coffee-centric, which brings me back to running 3 separate documentation tools: RDoc, CoffeeDoc and -- what? JSDoc?
I'm not completely adverse to running separate tools for the separate sources, but it becomes hard to reconcile that into a coherent result that doesn't feel like 3 separate Web sites.
So I guess my question is: what tool do you use or suggest? What language(s) does it support? Is it easy to browse, read, and actually find a needle in the haystack that is your project? I'm even considering rolling my own tool at this point, except that I can't believe no one else has encountered a problem like this (and I don't really want to waste time if I don't have to).
Sphinx directly supports javascript. Documentation of Ruby and CoffeeScript is supported through extensions (https://bitbucket.org/birkenfeld/sphinx-contrib/).
From the website:
The following features are present, work fine and can be seen “in action” in the Python docs:
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a module index
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm investigating different documentation systems for a project keeping up. Most recently I've been using DITA and the DITA OT, but its complexity makes me want to shoot myself.
Are there any systems that provide the following functionality:
Markdown support
Reusable content (I can refer to previously defined paragraphs or terms)
Localization support
Preferably, free or open source
Preferably, allows for multiple output
I wish I could use Pandoc for this, but it doesn't appear to support reusable content.
Edit: I just ended up writing my own library for this: https://github.com/gjtorikian/markdown_conrefs
If you don't mind reStructuredText instead of markdown, Sphynx is worth a look.
You could use pandoc + pre or post processor.
That way you could easily implement snippet reuse.
This is a topic close to my heart. There's quite a lot of Markdown processor options out there, but at time of writing those are more a case of personal solutions to this persistent problem. We all tend to get frustrated, make something to help in the short term, and share it.
The challenge has been to extend this to something built for purpose and at scale. Which is where I've turned my focus to over the last few years. That includes first working on PressGang CCMS inside of a tech writing team at Red Hat, and then being inspired to spin out Corilla, a dedicated technical writing startup building the tool you require.
PressGang (the prototype)
Please refer to the PressGang CCMS project for an idea of what we did at Red Hat to build tools to solve this. The lead engineer did a run-through video that you can see on Vimeo, and I've created a public Amazon AMI if you wish to try it. It's not being maintained but it's all open source.
It's a relatively large stack written for the most part in Java, but was useful as a look into an open source project in this space. But with bias I'd suggest...
Corilla (the product)
We cofounded Corilla as an open source company to focus on bringing together the elements of content reuse and collaboration with the ease of Markdown and Asciidoc. I've spent years writing DocBook XML, and quickly built my own snippets for Sublime Text to minimise the considerable overhead of authoring in that markup. The tide is of course turning. We need easier ways to write faster, and we need them to be discoverable, reusable, and allow the entire team to generate the content in formats they require.
I'd encourage you to get involved with the beta, as the technical writing and developer community is driving the project, and as we solve our problems together. Being able to resource and drive this to market is far more rewarding than having to pick through incomplete processor chains. I've been there, it's time we did more.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
Im trying to find a piece of software to help a small (~3-5 people) team write A) a user guide and B) an API reference for the extensible parts of the software. We quite like the idea of using a wiki of some form, but have a few specific requirements:
The ability to export the manual(s) into both online and offline readable forms (eg, a bunch of HTML files that can be put on a web server or read locally)
Automatically create pages from XML documentation. We are writing in VB.Net/C#.Net, and most of the API specific stuff already has XML documentation comments. It would be great if the API portion of the manual could specify the classes, methods, arguments etc, but also allow the writers to link to these pages from others. (eg, have a page that details the foo class, and be able to have a page that details how to do some general task with the API link to the page for the foo.increaseBarCount() method).
That's just about it, other than the obvious ('easy to use', 'do all the writing for me so that i can get out of the tedium of writing technical documentation', 'not cause a global thermonuclear war').
Does such a piece of software exist? Can a similar system be cobbled together using mediawiki extensions?
As to "automatically create pages from XML documentation", the obvious solution would by doxygen. It creates documentation (HTML, PDF, WinHelp ...) from special doc comments embedded in source code. It handles Javadoc comments, Qt style comments and XML comments. If you generate HTML, the page names are predictable, so easy to link to; doxygen can also create internal links automatically. If you use other formats, you can probably embed some sort of anchor to refer to page names, but I'm not quite sure about that.
With respect to general documentation, we have good experiences with using a wiki. We use MediaWiki (of Wikipedia fame), but any decent wiki will probably do.
We have never tried printing it, but Google shows various solutions for printing from MediaWiki, so you can probably make something work without too much hassle.
The main thing we like about using a wiki for docs is that you can easily change them when you detect a mistake; that keeps them fresh. Also, no worries about having an outdated copy.
You could check out Atlassian Confluence. I believe that they have a free version (possibly just an offer, so you may end up paying in the long run, don't know) for small teams. They also have an API, so it wouldn't be too hard to write a utility to extract the XML C# documentation and create pages from it using the API, if nothing already exists.
The wiki is easy to use and is used quite a bit by open source projects. You can look at
the ANTLR Documentation, which is Confluence, for an example.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I work at a company that, for some reason, insists that all our development documentation should be in MS Word format. Which, being a binary format, means we cannot:
Diff versions of a document against each other (so peer reviewing them is a pain - because of the domain we work in, peer reviews for all changes are essential)
Grep a folder-full of documents for keywords
What do you use to write documentation in and why?
Please also give me ammo to change this situation with...
I recently started using DocBook XML to author my documentation.
On the upside, it's a pure text format. You can break a large document into multiple files, and use nodes to bring them all together into a single book. Table of contents and index are automatically generated. Intra-document links (within arbitrary text, pointing to chapters or sections) are very easy. And with a push of a button, I can create a single-html-file version, a chunked-html version (one file per chapter), and a PDF version.
After some tweaking and customization, I'm very happy with the output. The documents look great!!
DocBook is used extensively by real publishers (most notably, O'Reilly), and it's been around for more than fifteen years, so it's reached a certain level of maturity.
On the other hand, all of the processing is done with XSLT, using an ad-hoc collection of tools. (My own docbook pipeline includes Python, Java, Xerces, Xalan, Apache FOP, and PDF-SAM. Plus the official XSLT stylesheet distribution, and my own XSLT customizations.)
DocBook is not a turnkey solution. You won't be able to get going quickly, without reading the manual. And if you don't know anything about XSLT, you'll have to learn.
On the other hand, there are only a dozen or two XML tags that you really need to know to write the documents. (The real expertise comes into play during doc generation from the XML sources.) If one person on your team was willing to be responsible for writing the doc build script, then everyone else on the team could just learn the DTD and do a decent job contributing.
Anyhow... DocBook definitely has some faults. It's not the easiest system for tech authorship. But it's the best open source tool I know of.
The "Subversion Book" is written in DocBook. Here's a page with links to the different book versions (single-html, chunked-html, and PDF):
http://svnbook.red-bean.com/
And here's a link to the DocBook XML sources for the first chapter, so that you can get an idea for how it works:
http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml
For ammo, there's the trusty old Pragmatic Programmer, chapter 14: The Power of Plain Text.
As Pragmatic Programmers, our base
material isn't wood or iron, it's
knowledge. We gather requirements as
knowledge, and then express that
knowledge in our designs,
implementations, tests, and documents.
And we believe the best format for
storing knowledge persistently is
plain text. With plain text, we give
ourselves the ability to manipulate
knowledge, both manually and
programmatically, using virtually
every tool at our disposal.
We use a wiki (specifically the one provided by Trac) for the two reasons you mentioned. Plus, if we really need to we can get the text version of the markup and manipulate it in a text-only environment, too (e.g. as part of svn comments during commit).
A format that can be easily reduced to text-only (non-binary) is definitely a must. Having the ability to upconvert it to a pretty format like a PDF is, for us, not terribly important.
Word has change tracking for documents (although it only works up until you accept the changes) and you can also grep them (the text isn't encrypted). So I'm not sure either of your arguments will hold up under scrutiny. I'd love to give you the ammo to change this but I've become jaded and cynical with age.
We use MS Word for our docs (which is a huge improvement over the earlier choice (Lotus WordPro - ugh!).
We use a wiki - specifically Confluence by Atlassian.
It's a commercial product, and it's great. One of the reasons we picked it over free/open wiki engines is that it has a full-blown WYSIWYG editor and various other features that make it more easily accessible to users who are familiar with Word.
We've also come up with a neat trick where we store images, designs, wireframes, etc. in Subversion, and then embed links in the wiki documents to those resources URLs via the Apache/SVN web interface module; notes on how we do this are here if you're interested.
Like Dylan's organisation, we also use the excellent Confluence wiki. I wrote an article about why this is better approach called Wiki is my word-processor, which should give you some reasons to change the situation.
Benefits of using a wiki for internal documentation include the following.
Word-processor users get sucked into changing the layout and typography, however good your templates are, which wastes time and reduces consistency.
A wiki provides full-text search, which you are unlikely to have for your body of the MS Word documents written by everyone.
A wiki provides a document version history; I have never heard of a team successfully keeping all revisions in Word documents and always being able to compare old versions, or using a version control system (with the possible exception of SharePoint but that's whole different failure scenario).
A wiki makes hyperlinks between documents easy; it is too hard to reliably link between documents in a collection of Word documents, so new documents end up duplicating older content into new monolithic documents which means they take more time to read and write.
Separate wiki pages can be edited by different people at the same time, and Confluence can merge changes when multiple people edit the same page at the same time; collaboration is harder with a Word document that only one person can edit at a time.
A wiki like Confluence automatically generates navigation pages based on wiki structure and tags; you need a librarian and lots of discipline to make it possible to browse a large collection of Word documents.
A wiki page usually loads and displays more quickly than a Word document.
A wiki page has more automatic meta-data; you need templates and discipline to make sure that Word documents always have Title, Author and Version set in the document properties and visible in the document on-screen and in print.
If you want more ammunition than this, then there is lots of wiki-promotion on The Atlassian Blog.
You could ask for documentation to be in OOXML (.docx, in the case of Word) format. Not as ideal as using ODT, in my opinion, however, it's still just a zip file with a bunch of XML files inside. :-)
A textual format facilitates merging your documentation with generated items such as JavaDoc, API references or data dictionaries. It also scales much better than word, which is hard to use for large documents. Finally, a format that allows includes allows multiple authors to work on a document concurrently.
LaTeX and FrameMaker (the two systems I have used for this) both have vastly superior indexing and cross-referencing capabilities and have either a native textual format or a textual version of their native format that can be included (MIF in the case of Framemaker). They are also both much more stable than word.
I've built tools that read data dictionaries and generate documentation that can be included into a larger document with stable indexing and two-way cross-referencing. The functional specification for This product was done with LaTeX in this way and got me another gig with the company. I have also developed a similar process with FrameMaker.
Is the entire development team against this requirement, or is it a small group? If it's the entire team, just ignore the mandate and use a text-based format -- wouldn't be the first time employees ignored a silly rule. Works especially well if you've not made a big fuss about it in the past. If you have, management might look especially hard at your docs.
MS Word supports document changes tracking and peer review.
The new MS Office format is fully XML based (to see this, rename a MS Word .docx file to a .zip, then unpack it to see).
Maybe Office 2007 may fit both your company requirements and your concerns ?
You can at least compare Word documents, see the "Track changes" command in the "Extra" menu, or use software like DeltaView. Found via google search first link at lifehacker.com. Searching in word documents should be possible with Google Desktop Search or other similar programs that index all files they are able to read.
Do they insist that you write it in Word or only that it's available in Word format? You could write in a text format and convert it to Word automatically.
Don't you store documentation files in some kind of Version Control System, ideally together with the source code? I would recommend to do this (makes it easy to get the documentation for old software releases).
And if you do store the docs in VCS, you will notice that plain text or XML-bases files are much better for this, because you can get diffs; also, changes between text files are usually stored more efficiently than changes between binary files.
Not to defend MS products here, but MS word can diff documents.
If you use Beyond Compare as the diff tool for your source-control system (As we do, with Perforce), it will show you differences between revisions of your Word docs. Admittedly, it only shows the textual differences - formatting changes are not shown - but this is usually enough for you to see what changed.
This is just another reason to invest in Beyond Compare, as it is one of the most polished pieces of software I've ever used - and it's the best $30 dollars (Less if you buy several) I've spent on software
There are many tools for word document comparison. I currently use a python script that puts a command-line on the built-in compare and merge functionality of word.
http://nicolas.lehuen.com/index.php/post/2005/06/30/60-comparing-microsoft-word-documents-stored-in-a-subversion-repository
It should be easy to automate word to extract all text from a word document into a text file. So you could write a script creating text files from word docs, and grep, compare, version control, Review these text files.
Of course this is not an ideal solution, since you loose your pretty formatting, but it should work.
I think there are programmes that convert Word docs to plain text. Use one of them to convert the word doc to plain text and then use diff, grep etc
Also have a look into recommended toolchain(s) for DocBook.