We are writing documentation for several of our software applications. Those documentation documents share some common content fragments (eg corporate profile, etc.).
I need to find some decent DMS that would allow us to manage the fragments of the documentation (the common parts and the product-specific or document-specific parts) and assemble documents from them. We'll also need to handle versioning.
Does anybody have experience with this?
Have to tried writing your documentation in LaTex. In this tool you can write simple scripts or create reusable components, which you can use in other documents too.
Here is the link to get more information.
In case somebody is solving the same problem, I solved it with MadCap Flare in the end.
Related
Sourcegraph- this site help me find usage of some of the libraries and usage examples provided by others, where official documentation of the libraries would go only so far. This has been incredibly valuable to me as a developer.
I'd like to see how other developers have used some APIs. We are working on a really huge team. Of course there are all sorts of permissions restrictions for multiple projects. However, most of the code is open. It really is a valuable asset to people like me.
TFS is a source control provider, I think it should also have something inside like sourcegraph. My question is- What's the best way to do this in TFS?
Suggest you to upgrade your TFS to TFS2017. This new release includes our most recent feature innovations and improvements. One of important update is code serach.
Code Search
Code Search provides fast, flexible, and accurate search across all your code. As your codebase expands and is divided across multiple projects and repositories, finding what you need becomes increasingly difficult. To maximize cross-team collaboration and code sharing, Code Search can quickly and efficiently locate relevant information across all your projects.
From discovering examples of an API's implementation, browsing its definition, to searching for error text, Code Search delivers a one-stop solution for all your code exploration and troubleshooting needs.
Code Search offers:
Search across one or more projects
Semantic Ranking
Rich filtering
Code collaboration
For details, see Search across all your code.
Sourcegraph now supports full-regex search across all code and is now deployable as a single Docker image (https://about.sourcegraph.com/docs) and indexes any Git-based code host.
My company has developed several projects. With time, we have found that certain functionalities were implemented more than once in more than one project.
Now we're aiming at extracting the common code into reusable components.
However, we need a tool to work as a cataloge for all reusable components, so that whenever a developer needs to search if a functionality was already implemented into a component, he can search this "reusable components" tool and if found, he can read a quick description of what this component does.
My question is: Are there any free tools out there we can use to document our reusable components?
Thanks...
I think you are looking for a wiki.
For example, take a look at DokuWiki. It's free software. It only needs a server with PHP (no database).
Each snippet/component can be on its own page (markup for code with syntax highlighting available). And you can link all pages. So you'll organize a structure that suits your needs by linking pages.
All users can edit (if you want to allow that) the pages. And you can restrict the access to the wiki (so only your employees can read/edit the wiki).
There are many other wiki softwares, of course.
Yes, there are free tools out there, such as doxygen and Javadoc, which can be used to help in documenting your code and components.
All such tools, though, require assistance from programmers; both the tools I've mentioned require adherence to some discipline in making comments in the code in particular formats. Automatic generation of useful documentation from code which has not been specially annotated is, I confidently assert, well beyond the capabilities of any available (free or costly) documentation tool.
If you edit your question with details of the programming languages and other tools you use you may get more useful answers than this one.
I am willing to build a wiki-based website that would have some other features, namely comments, social sharing, video insertion, article rating and gamification. In a nutshell, something very close to the StackExchange's websites, but the pages would consist of a single piece article instead of a thread of questions implementing the footnote feature.
I have not coded a single line yet.
I am rather experienced with Grails, so I know Groovy and Java. I also know JQuery and a bit of PHP, but I can learn basically everything required. I will be the only one programming on the project.
My questions are:
Which technology should I use according to YOU ?
Should I use Grails as this is what I know best, and try to integrate a wiki technology within my app (if yes, which one) ?
Should I start from an already existing wiki technology (WikiMedia, XWiki, TWiki, Moinmoin, ...) and modify it to integrate the features I need (gamification, comments, video insertion, article rating and social sharing) ? Once again, if you think that is the best solution, please quote a technology, and if possible, tell me why is this THE one.
Thank you very much for your help. I find it rather hard to choose, and ever harder to know which path is the right one to go.
Any suggestion is most welcome.
I would suggest using MediaWiki for the following reasons
You mentioned a wiki-based website
It has lots of extensions built already for your needs (comments, article rating, sharing, comments)
Since you mentioned you know little PHP, you can also modify some of the extensions for your use.
MediaWiki has (via extensions) support for social sharing, video insertion and article rating, and not-great-but-okay support for comments. (Probably most other wiki platforms too - these are common enough features.) Wikia (a MediaWiki-based wiki farm who opensourced most of their custom code) has some gamification features, though I am not familiar with them. Also, MediaWiki has the advantage of having the most widely known wiki dialect (due to the popularity of Wikipedia).
That said, if you are going for minimal developement effort, I would look into adding wiki features to an existing StackOverflow clone before trying to add gamification, comment etc. features to a wiki.
I want to create a community around a current iPhone app I've built. It will allow registered users to upload and download small configuration or settings files, which are used in my app to customize functionality. These files are serialized plists (binary files around 500 bytes), but can be converted to a JSON or XML format if necessary.
I do not need an HTML front-end; I plan for it to be accessed only via my app. Files do not need to be private or secure. I do not plan to store or ask for any user private data--just a login and password.
I'm looking for tips that might get me close to my goals with the least amount of effort - I want to focus on the core functionality of the app, and have this as a stable feature that I can add to in the future if it is useful. I would of course prefer FOSS, but a commercial solution is not out of the question. Things like file sharing sites with apis, login ideas, and so on.
So, what software solutions are out there that I may not be aware of? I know that Drupal has modules to allow user logins. Is there something that would work not as a web app, but as a service only? Dropbox has file sharing and an API, but I'm not sure I could use it the way I'm intending.
In short, I could code this, but would prefer a pre-baked solution that would deal with things I may not have thought of. I am sure there must be something out there which I can use.
More Details, and what I plan on the service offering:
Registration of users via the iPhone, and all that entails (will code the UI myself--I just want an API to connect to)
Viewing of these files quickly and efficiently (the files were built with performance in mind, and this is a free app, so I would like to keep server costs down)
Uploading their own files, with a few integrity checks
Rating the files
Gathering statistics on usage (which files were downloaded most often), etc., to provide a way for the files to be ranked by rating, popularity, etc.
Optional - submitting revised versions of the files (a tree).
Optional but preferred - statistics on users (no. files uploaded, perhaps rewards system for sharing)
I'm just not up to date with current technologies and open source solutions. I have experience in SQL, relational database design, and have built backends in Java, so a custom solution is not out of the question. However, it's been a while, I'm not a security expert, and would prefer to not reinvent the wheel for what is a fairly simple project, so an off-the-shelf solution would be preferred.
Check out www.parse.com!
It is absolutely brilliant for stuff like this.
You may want to look at source versioning systems like SVN or distributed systems like Mercurial or GIT. Both would be much better if the data were serialized to a text format, like JSON or XML as you mentioned.
Registration would need to be done by you of course
Viewing of files (including changes, of course) is quick and efficient. The interface can be done in a number of ways, even simulating command-line.
Uploading files will of course work, and changes made will be stored as diffs. Integrity checks can be done, for example, by Mercurial plugins
Rating the files probably can't be done directly unless you wanted an awkward hack involving parsing change entries or writing a plugin.
Submitting revised versions of files would work as that is the raison d'être of versioning systems.
Some statistics are made available in VCSs.
This is honestly a bit of a strange use for version control systems and not altogether elegant, but sometimes that's what innovation is about.
I suggest TikiWiki .
Pros:
Out-of-the-box all you need to build a community. (See reference below for list of features)
It's FOSS
It has 200 active developers - so it really has a lot of momentum.
Cons:
So many out-of-the-box features that it suffers from feature bloat. Configuration and initial set-up may be complicated.
Not really oriented to mobile platforms.
The majority of components available for Delphi do not have HTML Help files for Delphi 2009. Many components including some very popular commercial components only have HLP and CHM help files.
Many of the third-party components are no longer being actively developed but are used by many developers. As a result there is no IDE help for these components.
There were very few complaints about the old CHM help files but today there are a large number of complaints about the help file system. Maybe it is time for Codegear to rethink the type of help file system used.
One of the complaints that I have about it is even when you install components that provide HTML help files the Contents Tab becomes corrupted where by previously installed component contents are removed.
Are there possible alternatives for Codegear to consider?
I have the same feeling. The old help system helps me more quickly to find an answer.
One idea is to maybe to model it after the Delphi Wiki at: http://delphi.wikia.com/wiki/Delphi_Wiki
The wiki actually isn't set up that bad, especially with the VCL link in the left frame.
It's fairly pleasant to look at, has a decent search, includes issues, examples, cross references, and what I like the most: user comments and tips.
Actually regarding the user comments and tips, the thing I like most about the PHP documentation at www.php.net/docs.php (which I think is the best programming documentation I've seen) is the user comments and tips.
If they can integrate the great layout that you'll find at Delphi Basics into it, and allow 3rd party components to add their help files into it, then they'll have a complete reference. (But the 3rd parties will obviously have to restructure their help files to the new format - whatever it ends up as).
The wiki also has sections for Tutorials, Tips and Tricks, References and Popular Articles. And I think it could also become the all-encompassing code-repository we all would like.
An option to download the help wiki should be allowed so it can be accessed offline.
And they'll have to figure out how to get the F1 key to work to properly search the wiki/help file, whether online or offline, and give the most relevant results.
The trouble with the Wiki now is that it is not complete, and the full set of Delphi help files need to be incorporated into it.
This might be a pipedream, but something like this would be my ideal.
This is a pet hate of mine. The Delphi Help has just got worse, although with a recent slight improvement. I honestly believe that this is one of the things holding back its adoption.
Micosoft introduced Help3 for VS2010, so maybe we will see it in Delphi too:
here is a blog post which answers the question "Why A New Help System?"
http://thirdblogfromthesun.com/2010/10/the-story-of-help-in-visual-studio-2010/
It quotes an internal paper, which led to the new "Help3" project in
early 2008:
"The paper described the following
issues with the help experience in
Visual Studio:
Not being able to find the information you need is a common
problem. F1 Help and Search do not
work as well as they should.
The performance of the help system – primarily start-up, topic-load,
local search results – is one of the
biggest problems.
The offline MSDN library install is fragile due to the complexities of
the help system.
The proprietary nature of our help format offers little incentive for
partners to develop authoring tools
and cannot be easily adopted by
developers in their own products.
On the content production side, the help platform saddles us with
outdated tools and processes.
Finally, and most importantly, no single team at Microsoft owns solving
these problems."