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
Related
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 looking into writing documentation about some functions but do not want to write the documentation in the source code.
Is there a template I can follow, e.g XML, or something which can generate some sort of Javadoc-ish looking style documentation?
There's docbook, but to be fair, docbook excels at book or manual style documentation. It does do website documentation, but its websites tend to not be as heavily interlinked as javadoc. This is an example of a docbook document rendered to a website.
Docbook excels when you have one "source document" that doesn't have a presentation in the real world, and a few "rendered documents" that all must contain correct, up to date information built from the source document.
It is hard to understand what you are looking for, mainly because it seems that you are not exactly sure yourself. Javadoc is documentation that was purpose designed to document Java code, so a "javadoc like documentation without source code" is a hard idea to follow. Perhaps if you sat down and thought about the main sections of documentation, you'd find an outline (which might heavily include the navigation you want to use). Then it would be much easier to fill in the blanks, because you have blanks.
You can use the javadoc engine to generate documentation. It is very configurable; and supports two kinds of plugins. One to add additional "tags" and one to add / override additional "layouts". However, these tags and layouts operate on an API that tends to be Java source code oriented, such that a "javadoc comment before a class" calls a method that effectively handles the javadoc for this class. As such, without Java source code (or something very like it) you have the wrong underlying API (unless you can bend it to your needs).
Maybe you are looking for something like Doxygen, an API-documentation tool that can also be used to write other documents (f.ex. the manual of doxygen was produced with Doxygen itself without normal source code.)
Another tool would be Sphinx, which can also be used for API-documentation and also manuals without source code (ex: Python documentation).
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 is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
let's say that in order for me to make clear how my program works or even for the own sake of documentation I am writing some text document in word or whatever text editor or online wit google docs, etc. Let's say that at some part of the document I open a new one and extend there the idea. Then later, I go back to the "master" document and add some hyperlink or just put reference (it follows in doc XXXX, page YYYY). I wonder what could be the fastest approach to do this
* google docs adding easily hyperlink? but how can I organize docs effectively?
* some text editor with this functionality?
Thanks for your responses
P.D. Are there easier solutions than WIKI's? In terms of easiness of installation and setup
Wiki's are definitely great for that. I have used two notetaking solutions that have what you want (I've used more, but these were the best for me).
TiddlyWiki
Great feature set since it's javascript/html with wiki functionality: intralinking to pages you create, embedding of images from any directory, hyperlinks, and printability
Also has an amazing amount of plugins at places like TiddlyTools and other repos like it
I combined it with TeamTasks which not only made it look better, but brought in some todo functionality; with TiddlyWiki Address Book (twab) for contact management, and several other plugins that worked great
emacs + orgmode
This is my top choice today for notetaking and all kinds of stuff
It is literally unbelievable. Todos, contacts, scheduling, linking, export to html, export to PDF via LaTeX, interfacing with gnuplot, TikZ, ditaa, R (like Matlab), etc.
Inter and intralinking are very easy. See THIS for specifically how orgmode deals with various linking.
Lastly, if orgmode sounds interesting, I would strongly recommend checking out the orgmode wiki, Worg, where tutorials, videos, and screencasts exist.
Your initial inquiry mentions simplicity, so perhaps one of the wikis is best. If you're unfamiliar with them, it's quite easy to just download a copy (just an html file), open it in a browser and play around. There's a lot of documentation out there to help you and your linking is as often as easy as writing something like [[page::section]] or similar in your document.
On the other hand, if you're looking for advanced usage and especially exporting of documents, I have yet to find anything to beat orgmode for me! I highly recommend it and the mailing list is very, very active and supportive.
Every document type or system has its own standard for interlinking documents. HTML has hyperlinks, MS Word has document references, etc. I personally find wikis to be the easiest way to grow and expand interlinked documents. HTML hyperlinks are probably the most common standard way of linking documents, and wiki syntax makes it especially easy.