I have to maintain a huge set of training material in forms of slides.
At a first glance, I've noticed there's no support for version control in OpenOffice OOImpress (but I might be wrong on this).
Which tool should I use to easily maintain my training material?
I thought about using LaTeX + Beamer so that I can easily put under version control the source code for the slides, but also non technical people should be able to update the material and I would prefer not to force them to learn LaTeX.
My preferred way of writing presentations is now using a Trac wiki with the S5 plugin.
S5 is a slideshow format that turns HTML+CSS+JS into a slideshow you can run in your browser. You can see an example slideshow here.
Instead of writing the S5 HTML by hand, I use Trac's S5 plugin to convert wiki syntax (similar to mediawiki syntax) to an S5 presentation. So a wiki page like this:
[[S5(theme=yatil)]]
= My presentation =
'''November 18 2009'''
* Steven Kryskalla
* skryskalla#gmail.com
* http://lost-theory.org
== Intro ==
* Topic 1
* Topic 2
* etc.
== How to X ==
First, install and configure...
{{{
#!python
#this turns into syntax highlighted code
}}}
== Resources ==
* http://www.example.com/
Turns into a slideshow with 4 slides. The == Headings == start a new slide, and the body of each slide can be text, syntax highlighted code, bulleted lists, numbered lists, images, tables, etc.
The wiki has built in version control so you can diff, revert changes, etc.
It probably wouldn't be that difficult to re-use the wiki formatter and S5 code to create a command line program that turned a text file into a presentation. That would allow you to keep the slide in your own version control system (svn, hg, etc.).
I sounds like you're looking for a Digital Asset Management System. You could try something like SVN with one of its GUI tools, or get something more involved like Canto's Cumulus.
Cumulus is something our company has used in the past, we no longer have a need for the system so my knowledge on the different kinds of systems out there is pretty dated.
Why not simply put OOImpress documents under something like Subversion or Git and use TortoiseSVN to let end-users manage the version-control bit.
Any good CMS offers revision control as well. But in general, any source control system can version any file, diffs won't be easy to do, however, since these items are in xml, they won't diff well.
This is an old question, but because I have run across the same issue recently, I would like to share solutions I considered or used, in the hope it may be useful for the next person who runs across this question:
The simplest solution is to use Powerpoint or similar software online, converting LaTeX to images, and to use their built-in version control. Answers to this question detail how you can diff such versions.
You could use a Markdown-based solution. My eventual choice was AsciiDoctor because it's free, well-maintained, and does what I need. Madoko looks even better, and is more oriented towards LaTeX, but does not seem to be maintained. Both solutions are based on the reveal.js framework. There is also GitPitch which is a git-based Markdown solution, but its freemium model puts me off. Fusuma is another solution a Google-search suggested.
Related
I'm a noob in scripting (for years now...) and a BBEdit fan user. I usually find solutions to my problems on StackO or GitH, but this time I do not, and I finally decide to create an account. First post on Stackoverflow ! So stressful !
BBEdit works really great for what I do. But there is 2 things I try to do and I definitively need to know if it's possible or if I change for Atom (wish do it well)... and it will be very painful. I can't stop a such love story without be absolutely sure of... I just can't write it.
So first I use a lot MD with the great Preview CSS from Ryan Dotson.
BBStylish – Attractive Markdown Preview CSS for BBEdit
<https://nostodnayr.net/projects/bbstylish>
Made by Ryan Dotson – rd#nostodnayr.net
Version 1
14 October 2019
I'm really happy with this one but it doesn't deal with tables or MMD stuffs. Is there a CCS somewhere to previewing MMD ? Or there is way to had a part of code to the Ryan Dotson CSS to do this ? I think, if I have no answer, I will ask him directly...
Secondly, is there a way to use Mermaid directly in BBEdit with a plug-in, or a CSS, or magic trick,,
Thanks a lot.
Tschüss
GG
You can use BBEdit's "Preview Filters" feature to set up MultiMarkdown as the preferred renderer for using "Preview in BBEdit". There's pretty detailed information on how to do this, see the "Previewing Pages" section in the user manual (itself available on the Help menu).
Beginning in BBEdit 13.1 (in open beta testing at this writing, check #bbedit on Twitter for the news) you can also select the default Markdown renderer (and MultiMarkdown is an option, if you have it installed) in the Markdown language-specific preferences.
I'm using CKeditor 3.6 and find myself in need of writing a simple plugin. What I need is a button that works much like the format buttons (bold, italic, etc.) except that it will turn this:
SelectedWord
not into, say,
<b>SelectedWord</b>
but into:
SelectedWord
I've tried looking into the various plugins that come with CKeditor, but quite frankly, they are more confusing then helpful. I've read the tutorials, I know the basics of writing a plugin, but what eludes me is the functionality itself.
You are going to have to hack the CKEditor code base, but let me tell you that hacking around ckeditor is not so difficult. Also, there are versions of the older fckeditor floating around. Compare the two and see which one would be easier to hack for your mod. I have had to use the older version specifically for creating pinholes against Coldfusion so I could use the file upload segment of the tool. And in another case to function against domain cookies, because of security issues with regular cookies. FCKEditor and CKEditor has never been a clear install for me with the base product. I hope this is somewhat helpful.
Given a project I'm about to start there will be documentation produced.
What is the best practice for this?
Should the documents live with the code and assets or should there be a separate documentation store?
Edit
I'd like a wiki but I will need to print the documents etc... It's a university project.
It really depends on your team. Where I work, we keep documentation in a wiki which is linked in with our team website. For the purposes of shipping documentation, the wiki can be exported and we run it through a parser that "fancifies" the look and feel of the documentation for customer purposes.
Storing the documentation with the code (typically in your source repository) is not a bad idea. Just make sure to keep them separated. For example, keep a docs folder which is on the same level with your src folder in your repository. This way, you can quickly ship the current documentation, you can easily track revisions, and anybody new to the project can immediately jump in without having to go to multiple locations for information.
Storing it in source control is fine.
This is an interesting question -- basically, what others are saying is right about generated documentation, source files and templates/etc. should be stored in source control and generated during your build process.
As far as requirements/specs/etc. documentation, I have worked both ways, and I very much prefer using SharePoint or a Wiki/document portal that is designed for document sharing/versioning. The reason is, most non-developer folks aren't comfortable working with source control systems, and you don't gain any of the advantages of intelligent merging if you are using a binary format like Word. Plus it's nice to have internet-based access so you can reference and work on the docs in a distributed team without people having to install extra software.
Here's a 2017 summary of the options and my experience:
(extreme 1) Completely external (e.g. a wiki, Google Docs, LaTeX, MS Word, MS Onedrive)
People aren't bothered about keeping it up to date (half of them don't even know where to find the page that needs updating since it's so out of the trenches).
wiki platforms are “captive user interfaces” - your data gets stored in their proprietary schemas and is not easy to examine with a simple text editor (Confluence is even worse in that you have no access to the plaintext content at all anymore)
(extreme 2) Completely internal (e.g. javadoc)
pollutes the source code, and is usually too low level to be of any use. Well-written source code is still the best form of low level documentation.
However, I feel package-info.java files are underutilized.
(balance) Colocated documentation (e.g. README.md)
A good half way solution, with the benefits of version control. If a single README.md file is not enough, consider a doc/ folder. The only drawback of this I've seen is whether to source control helpful graphics (e.g. png files) and risk bloating the repo.
One interesting way to avoid this problem is to use plaintext diagram tools (I find Grapheasy and Text Diagram to be a breath of fresh air).
plaintext can be easily read even if your rendering engine changes as the years go by.
Github's success is in no small part thanks to its README.md located in the root of the project.
One tiny disadvantage of this approach though is that your continuous integration system will trigger a new build each time you make edits to the README.md file.
If you are writing versioned user documentation associated with each release of the product, then it makes sense to put the documentation in source control along with its associated product release.
If you are writing internal developer documentation, use automated internal source code documentation (javadoc, doxygen, .net annotations, etc) for source level documentation and a project wiki for design level documentation.
I think most of us in the industry are not really following best-practices and it of course also depends a lot on your situation.
In an agile environment where you would have a very iterative process of release, you will want to "travel light". In this particular case, Jason's suggestion of a separate Wiki really works great.
In a water-fall/big bang model, you will have a better opportunity to have a decent documentation update with each new release. Also you will need to clearly document what version of the requirements was agreed on and have loads of documentation for every tiny change you do to requirements (due to the effects it has on subsequent stages). Often if the documentation can live together with the version controlled source code it is the best.
Are you using any sort of auto-documentation or is it completely manual? Assuming that you are using an auto-documentation system, the documentation is more or less generated on the fly, and would be part of the code itself.
To me, (assuming that it's possible with whatever code you are using), this would be the preferred method of handling it, as you wouldn't need to maintain the documentation source at all.
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
As a developer I really don't like writing documentation but when I have to I'd like to make the process as painless as possible.
The problem with Word is that it constantly gets in my way. I worry more about the layout than about the actual content ... that's why I'd like to get rid of Word.
Ideally I'd like to write my content and then 'compile' it into a document.
I've heard of LaTeX but I don't have any experience with it whatsoever. Would this be the right technology for the job? What editor (Windows) should I use? Is it a good idea to start with LyX?
EDIT: I'm not asking about documenting code (I use Sandcastle for that).
Update 2014:
We have now switched to GFM (GitHub Flavored Markdown).
It's really easy to work with.
Write code & documentation in the same IDE!
Everything can be versioned!
Get great output either as raw txt, html or pdf!
My solution to this was to invest some time in creating a decent Word Template for myself.
The important thing to do is make sure you have a Style defined for everything you can put in the document.
Once you have all the Styles defined and all of the document content tagged with the correct Style instead of formatted in an ad hoc fashion, you'll be surprised how easy it is to produce good looking Word documents quickly every time.
The wider problem here is that everyone spends hours in Word and yet it is very rare for companies to invest in Word training. At some point you have to bite the bullet and take the time to teach yourself how to use it properly, just like you would with any other tool.
Anything you can do with LyX you can do with LaTeX. LaTeX is suitable for all sorts of things; it has been used for everything from manuals to lecture slides to novels.
I think LaTeX is probably worth looking into as an option; if you've ever wanted to "code" for your word processor, LaTeX is for you. At the simplest level you can define new commands to do things for you, but there's a lot of power there. And the output looks really neat.
In my opinion, LyX is fantastic in certain circumstances, handy in others, and occasionally just gets in your way. I think it should be seen as a productivity booster for LaTeX. In other words, learn to use LaTeX before trying LyX. Both are of course free and available for Windows, though the learning curve is quite steep compared with MS Word. For long documents, or plenty of similar documents, LaTeX/LyX is probably a worthwhile investment.
I've found that wikis can be good for this. Find a wiki you like that lets you do a bit of formatting, but nothing really heavy. Ideally it should let you format code easily too - to be honest, the markdown available on SO is probably a good start.
That way:
You have change tracking built-in (assuming a decent wiki)
You can edit from anywhere
Everyone always sees the same documentation (instant distribution)
You can concentrate on content instead of formatting
You could write your documentation using your own XML format and then transform it into any format with XSL (e.g. PDF via FOP+XSL-FO ).
See also the DocBook XML format.
LaTeX is an extremely powerful tool and might well be overkill here as it is designed for scientific/mathematical literature. It has a (relatively) steep learning curve and can be tricky to coax to do exactly as you want if you're new to it. I LOVE LaTeX, but it is not really a general purpose word processor.
Have you considered OpenOffice instead?
LaTeX is really a very powerful language if you need to write documents.
Perhaps you can try texmaker, a cross-platform LaTeX editor:
Texmaker is a clean, highly
configurable LaTeX editor with good
hot key support and extensive Latex
documentation. Texmaker integrates
many tools needed to develop
documents with LaTeX, in just one
application. It has some nice
features such as syntax highlighting,
insertion of 370 mathematical symbols
with only one click, and "structure
view" of the document for easier
navigation.
What about using HTML? This way you could then publish the documentation if there will be need for many people to access it from many places.
Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.
My response to what I also personally find a deeply frustrating experience with MS Word is to avoid it altogether and use an auto-documenting tool like GhostDoc to generate XML from what I've already written in the code (DRY!) and deal with the XML from an XSLT based intranet site or similar later.
Are you talking about documenting your actual code? If so, I recommend Doxygen for unmanaged code and Sandcastle for managed code. Both will compile your help or build it as a website for you.
Both applications will read special tags above functions / classes / variables and compile that into the help.
Well I've never found anything wrong with MS-Word in the first place. (i.e if you take the time to know how to use it effectively). OpenOffice indeed is an amazing & credible free alternative - but then if you hate MS Word for layout related problems, the same problem is gonna occur with OpenOffice too.
Never tried the Latex system myself, but have heard its good for scientific work. I think using some HTML WYSIWYG editor would be best for you, if you want to just focus on the content.
I considered a wiki, but I decided to go with a modified Markdown notation, for the simple reason, that a wiki's content isn't easily exported and distributed outside of the wiki itself, while the Markdown can be rendered into HTML.
Answer to chris' question about my workflow: I write the documentation with a Notepad-like application (TextWrangler, only because of its word-wrapping feature) in its raw Markdown format. Then I have a small localhost documentation website with my modified Markdown parser (extended for a few features and a bit more HTML-oriented functionality) that checks for the timestamps for the documentation files - if a file has been updated, it parses that file into HTML, and stores the file in a cache.
This way I'm able to edit the source documentation on my desktop, and just press F5 in my browser to see the results immediately.
I haven't got around to trying it yet, but I've always thought AsciiDoc would be good for this kind of thing.
If you want something simpler than LaTeX, you can have a look at ReStructured Text
Read this book: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . There is some idee fixe inside, so that documentation should be built automatically. Think about using your IDE for this, or look for some additional tools. Most modern languages support generating documentation as you write the code. This can simply maintain your doc in touch with latest changes in the code.
I prefer to use a RTF editor which is a lot less clunkier than words. This way the formatting and all the headers/footers nonsense will not take up half your time. Wordpad has worked for me on several occasions. I'm stuck with Word for now though :(
there are a lot of possible ways:
embedded documentation, e.g. javadoc: good for describing APIs, not so good for the "big picture"
plain html: can be checked in under version control, a definite plus
a wiki, e.g. confluence -- great for collaboration, but has version control different from your source
LaTeX or somesuch: better suited for books or papers than typical documentation; support for graphics is cumbersome
an Office clone, e.g. OpenOffice: mostly the same as Word+Visio, but open source, with a nicer document format
I usually document the software structure (the "metaphors" of a project, component interrelations, external systems) up front, using Visio, in "freeform" UML. These are then embedded in confluence, which can be converted to PDF if someone wants a printout.
LyX
LyX is a WYSIWYM front end to LaTeX: You get the convenience of a document processor (somewhat similar to Word) with the consistency and power of LaTeX: It doesn't get in your way and can do a lot of things that professional writers need.
Note: The correct answer for you really depends on your way of thinking --- we can't decide this for you. This answer simply shows an excellent choice if you think of documentations as documents and want something similar to Word (where Word is good) that doesn't suck as Word (where Word is bad for programmers).
But many programmers think of documentation differently and hence prefer different metaphors. I myself had the same problem years ago, worked with LaTeX (as I am a mathematician), found LyX and finally settled on a Wiki/Source system that I wrote myself.
Vim is the solution for anything that means writing plain text in the most efficient possible way. If you need formatting, then use XML, Latex or something similar (in Vim).
Vim changed my life!
Simple answer: LaTeX sounds like just what you are looking for.
I use it for writing documentation myself. I will never go back to Word if I have the option.
At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.
Latex was chosen because we are academics, and latex is the tool of choice. I believe it didn't generate good enough HTML.
Docbook was chosen for power, but it was very unwieldy. It put us off writing any documentation: code had to be manually formatted, we kept forgetting the syntax, and it was difficult to read. The learning curve was also steep.
Finally, we moved to reST, using sphinx, and that was a great decision. Documentation is now very easy to write, and both PDF and HTML versions look beautiful (though the PDF could do with some customization). Its very easy to customize too.
The best bit about reST though, is that its human readable in source form. That is a wonderful advantage. I've switched to using reST for all my stuff now, especially anything over the web (except of course academic papers, where one would be foolish to use anything but latex).
You may want to look into doxygen at http://www.doxygen.nl/, see their nice examples. In this case, the documentation is presented by tags in comments in the source.
Another option would be to use an online system like trac from http://trac.edgewall.org/ which is a wiki/doc/issuetracking system that lives on top of subversion.
Say a development team includes (or makes use of) graphic artists who create all the images that go into a product. Such things include icons, bitmaps, window backgrounds, button images, animations, etc.
Obviously, everything needed to build a piece of software should be under some form of version control. But most version control systems for developers are designed primarily for text-based information. Should the graphics people use the same version-control system and repository that the coders do? If not, what should they use, and what is the best way to keep everything synchronized?
Yes, having art assets in version control is very useful. You get the ability to track history, roll back changes, and you have a single source to do backups with. Keep in mind that art assets are MUCH larger so your server needs to have lots of disk space & network bandwidth.
I've had success with using perforce on very large projects (+100 GB), however we had to wrap access to the version control server with something a little more artist friendly.
I've heard some good things about Alienbrain as well, it does seem to have a very slick UI.
GitHub recently introduced "image view modes", take a look: https://github.com/blog/817-behold-image-view-modes.
We, too, just put the binaries in source control. We use Git, but it would apply just as well to Subversion.
One suggestion I have is to use SVGs where possible, because you can see actual differences. With binaries (most other image formats), the best you can get is a version history.
A lot of the graphics type people will want something more sophisticated than subversion. While it's good for version control, they will want a content management system that allows cross-referencing of assets, tagging, thumbnails and that sort of thing (as well as versioning).
TortoiseSVN can show image revisions side-by-side, which is really useful. I've used it with different teams with a great degree of success. The artists loved having the ability to roll back things (after they got used to the concepts). It does take a lot of space, though.
Interesting question. I don't have a bunch of experience working directly with designers on a project. When I have, it's been through a contractual sort of agreement where they "delivered" a design. I have done some of my own design work for both web sites and desktop applications, and though I have not used source control in the past, I am in the process of implementing SVN for my own use as I am starting to do some paid freelance work. I intend to utilize version/source control precisely the way I would with source code. It just becomes another folder in the project trunk. The way I have worked without source control is to create an assets folder in which all media files that are equivalents of source code reside. I like to think of Photoshop PSD's as graphics source code while the JPEG output for a web site or otherwise is the compiled version.
In the case of working with designers, which is a distinct possibility I face in the near future, I'd like to make an attempt to have them "check-in" their different versions of their source files on a regular basis. I'll be curious to read what others with some experience will say in response to this.
We use subversion. Just place a folder under /trunk/docs for comps and have designers check out and commit to that folder. Works like a champ.
#lomaxx TortoiseSVN includes a program called TortoiseIDiff which looks to be a diff for images. I haven't used it but looks intriguing.
I would definitely put the graphics under version control. The diff might not be very useful from within a diff tool like diffmerge, but you can still checkout two versions of the graphic and view them side by side to see the differences.
I don't see any reason why the resultant graphics shouldn't be kept in the same version control system that the coders use. However, when you're creating graphics using PSD files or PDN files you might want to create a seperate repository for those as they have a different context to the actual end jpeg or gif that is produced and deployed with the developed application.
In my opinion Pixelapse combined with a backup solution is the best version control software for graphics that I've found thus far. It supports adobe files and a bunch of normal raster images. It has version by version preview. It autosaves when the files update(on save). It works like dropbox but have a great web interface.
You can use it in teams and share projects to different people. It also support infinite reviewers which is great for design agencies. And if you want you can publicly collaborate on projects that are "open".
Unfortunately you can't have a local pixelapse server, so for backup my current setup is that I have the Pixelapse folder(like a dropbox folder) inside a git repo for snapshot creation.
With respect to diff and merging, I think the version control is more critical for graphics and media elements. If you think about it, most designers are going to be the sole owners of a file -- at least in the case of graphics -- or at least I would think that'd be the case. I'd be curious to hear from a designer.
#Damian - Good point about the tagging and cross referencing. That's true; while I haven't working with many designers on a software development project, I have worked for a company that had a design department and know that this is an issue. Designers are still (perpetually) looking for the perfect system to handle this sort of thing. I think this is more suited to a design department for shared access, searching and versioning, etc to all assets -- where there is a business incentive to not reinvent the wheel wherever/whenever possible. I don't think it would apply for a project-oriented manner as tagging and cross referencing wouldn't be quite as applicable.
We keep the binary files and images in revision control, using Perforce. It's great!
We keep a lot of art assets, and it scales well for lots of large files. It recognizes binary files, the ones that can't be diffed, and stores them as full file copies in the back end.
It has P4V (cross-platform visual browser), and a thumbnail system so image files can be seen in the browser.
You might want to take a look at Boar: "Simple version control and backup for photos, videos and other binary files". It can handle binary files of any size. http://code.google.com/p/boar/
A free and slightly wonky solution is Adobe version Cue its comes with the Adobe Suites up to CS4 and is easy to install and maintain. Offers user level control and is artist friendly. Adobe has discontinued support though for it which is a shame. Adobe Bridge acts as the client between the user and the Version Cue server. If used properly its an inexpensive solution to version control. I use CS3 version cue with CS3 Bridge. Works great for small teams.