If you just want to create an HTML-documentation, what are the advantages of using Sphinx as a documentation api against using MediaWiki?
It really all depends on the workflow that you and, if applicable, people working with you, are used to. More than advantages it is a matter of taste and what you are used to. For me the perceived advantages of sphinx-doc are:
Easier editing of the files in an external editor
Version control of documentation using a VCS (svn, fossil or git)
I'm used to markdown syntax
But i think that for each of these points someone could argue an advantage for mediawiki, hence I think it is a matter of taste and preference.
However, if you are collaborating with non-technical people: mediawiki or fossil-wiki will be easier for them to add to the project / review pages and make corrections. By the same token if your documentation needs to be in sync with other documents (code or data) then sphinx-doc in the same version control system would have my preference.
I mention fossil-wiki because it offers a combination of both options and for some projects gives the best of both worlds. You can have wiki-pages that people can edit in the traditional sense (through an online front-end) and .wiki pages that are edited as if they are source and cannot be changed through the front end. Again, whether that makes sense to you depends on your use case and writing style and habits.
Related
Different kind of software offer different amount of configuration/customization. Routers are one of the most configurable software systems I know of. I want to know how routers handle configurations - how they alter the code flow based on the configuration?
One obvious way is to use if..else clauses provided by most of the language(let's assume we are using C)
So is there any other programming method(or paradigm?)
Data-driven programming paradigm may be viable one. Configuration can be thought of one of the input source and so can be used to alter the code flow.
What I need to know is, is there any papers and references that I can use to enrich my understanding. Not just routers any kind of software. If the question seems to vague, let me know I will add more details.
I don't know anything about configuration of routers, but your question states you are interested in configuration for any kind of software, so the following might be of interest to you.
I am the author of Config4*, which provides C++ and Java parsers for a particular configuration syntax. I suggest you do the following. Skim Chapters 2 and 3 of the "Config4* Getting Started Guide" (HTML, PDF) to get an overview of the configuration syntax and API. Then take your time reading the "Config4* Practical Usage Guide" (HTML, PDF), which discusses the "how to" for a variety of different ways to use configuration. Although the discussion in that manual makes use of the Config4* syntax and API, the principles could be used with another syntax, for example, XML. If you focus on the principles discussed in that manual, rather than the syntax, then I suspect you will start to develop some insight into how a router handles its configuration.
I develop an online, Flash-based multiplayer game. It is a complex game, and requires a lot of documentation to fully explain it to our users. Ideally, I would like to find MySQL-based wiki software that can provide these editable documentation pages outside of Flash (in the HTML realm) but also within Flash for convenience, and so that players can refer to the information without interrupting their game or having to switch back-and-forth between browser tabs. I am expecting that I would need to do a lot of the work on the Flash side myself, as far as formatting, for example, but I would like to feel comfortable in querying the wiki's database to get info directly. I guess this means that I need a wiki that is structured relatively "flat" or intuitively so that I can do things like:
Run a MySQL query that returns a list of all the articles (their titles and IDs) in the wiki
For each article ID in the wiki, return the associated content
This may mean that I have to limit the kinds of formatting I put into the wiki -- things like tables would probably be omitted since they would be very difficult, if not impossible, for me to do on the Flash side. And that is fine!
Basically I am just looking for suggestions for wiki software that is pretty easy to use, but mostly is technically simple enough on the back-end that interfacing with it directly via MySQL is not difficult. When interfacing with the database directly, I only need to READ data. Any time the wiki would be edited or added to would be done via the wiki's actual front-end application.
Thanks for any suggestions!
MediaWiki is the best-known and best-supported MySQL-based Wiki, used for plenty of complex game documentation projects like MinecraftWiki. The database is not all that simple, but it's well documented and basic read operations aren't too hard. For example, here's how to fetch the current content of the page "MyPage":
SELECT old_text FROM page,revision,text WHERE page.page_title="MyPage" AND
page.page_id=revision.rev_page AND revision.rev_text_id=text.old_id;
(And yes, old_text is the current content of the page. Don't ask me why!)
Your main problem will be figuring out how to parse MediaWiki markup, there are plenty of parsers for it but I'm not aware of anything that would work in Flash.
I'm a relative newbie to web development. I know my HTML and CSS, and am getting involved with Ruby on Rails for some other projects, which has been daunting but very rewarding.
Basically I'm wondering if there's a language/backbone/program/solution to eliminate the copypasta trivialities of HTML, with some caveats. Currently my website is hosted on a school server and unfortunately can't use Rails. Being a newbie I also don't really know what other technologies are available to me (or even what those technologies might be). I'm essentially looking for a way to auto-insert all of my header/sidebar/footer/menu information, and when those need to be updated, the rest of the pages get updated. Right now, I have a sidebar that is a tree of all of the pages on my website. When I add a page, not only do I need to update the sidebar, I have to update it for every page in my domain. This is really inefficient and I'm wondering if there is a better way.
I imagine this is a pretty widespread problem, but searching Google turns up too many irrelevant links (design template websites, tutorials, etc.). I'd appreciate any help.
Oh, and I've heard of HAML as a way to render HTML; how would it be used in this situation?
Server Side Includes.
Old as time. Supported in most hosting situations. Often forgotten in favour of hugely overcomplicated templating systems. SSI still has a place.
You use a template language.
Most often this will be processed on the server, but there are offline solutions which you run though a utility to generate complete HTML documents for uploading.
I'm rather fond of Template-Toolkit which I usually use server side with Catalyst but it also very usable before you involve a web server using the ttree utility.
...........Wordpress?
I'd recommend Drupal. The tree structure of a menu is an inbuilt function and you basically can forget about it at all. And inserting whatever you want in specified areas (footer, header, whatever's defined in a template). It relies on PHP and MySQL - that stuff can be used on almost any server. And it has a moderate learning curve, so you should be able to start doing magic in little time.
Later this year I want to release a PHP framework that I've been working on as open source. I do use source control (SVN), but it's on an extremely limited basis. I'm self-taught, I develop by myself and don't have the experience of working with large teams. I have some ideas about what can help make a project successful, but I'm fuzzy on some of the details. Since it's not yet released, I want to do everything I can to set up the right infrastructure from the beginning. What do I need to know in order to setup and manage a successful project?
Some ideas that I have to make it successful (beyond marketing it):
Good documentation and tutorials
Automated unit tests and builds to
push update to the website
A clear roadmap
Bug Tracking integrated with the
source control
A style guide to keep the code
consistent
A forum for the community to get
support, share ideas, etc.
A good example application built with
the framework
A blog to keep the community informed
Maintaining backwards compatibility
wherever possible
Some of my questions:
How do I setup and automate a one
step submit-test-commit-generate API
docs-push update to website process? Edit: Would Ant or Maven be good candidates for this? If so, do you know of any resources for setting up a PHP project using them?
How do I handle (technically)
submissions from other users? How can
I ensure that those submissions must
be approved before being integrated?
What are some of the pitfalls that
can be avoided in terms of the
project community? I'd prefer to have
it be as friendly and helpful as
possible without a lot of drama.
I'd love to learn from your experience on any of these points. If you think I'm missing anything big, please share that as well. Any resources (preferably geared toward a beginner) that you could point me towards would also be greatly appreciated.
I'm just getting started in community projects, but I'll give you some advice on what I know.
How do I setup and automate a one step submit-test-commit-generate API docs-push update to website process?
I've never implemented it as one process. You could just have a checklist, and possibly even create some scripts to do certain tasks. I've never worked with any source control that automates the uploading and such to be done by a script. Most of the time, there is some web interaction to be involved.
You don't want to push API changes until it's an official release.
EDIT: Working Environment
For PHP, most of the time, I either edit directly on the server and test it there, using a beta.example.com, or similar, before pushing to example.com. You could also set up an web environment on your home PC (using XAMPP for Windows, or the standard LAMP installation on Linux). You would probably just use a mirror of your repository here, so you'd do svn commit, or whichever is appropriate for the VCS or DVCS you choose.
The fun part is testing this with different PHP versions. I've not done this myself, but you could probably use a .htaccess file to run a different PHP binary in order to test it out. I'm not really sure what the best option is for this is.
I've not done much with API, as I've never created a library, but just doing a quick search I found http://www.phpdoc.org/. It looks like a mature project, so that might be a starting point.
As far as creating releases go, I generally create a script that only includes the files that are part of the distribution (it will filter out any VCS files, and anything that you don't want in the distributed file). You could write a script around find on linux (which is what I do most of the time), or there may be other better options.
How do I handle (technically) submissions from other users? How can I ensure that those submissions must be approved before being integrated?
This is mostly handled by the bug tracker, and limited access in the Version Control System. Usually, you, and the people you allow, can commit to the VCS. Other users can submit patches, but then you might have someone review the patch, test the patch, and commit. You could split these tasks up as a team, or assign a patch to one person and have them do it all.
What are some of the pitfalls that can be avoided in terms of the project community? I'd prefer to have it be as friendly and helpful as possible without a lot of drama.
I would just make sure to keep it as positive as possible with the project members and community. There's going to be some disagreements, and it will drive a few people away, but as long as you have a stable product that meets the needs of most people, I think that's all that anyone can expect.
One minor suggestion that's worked well for me: start using first-person plural pronouns, rather than singular ones. That is, talk about "we" and "us" rather than "I" and "me." It encourages other people to participate when they feel like part of team, rather than when they feel like they're contributing your own self-aggrandizement.
The most important thing you have to do is to attract users. Without users, you won't get any contributions and developers helping you out. Because developers are users first, and then they decide to extend/fix something they use and might become contributors.
So to get users, you should consider
describe what your framework does in one or two sentences at the top of your project page
mention how your framework can be used and for what, what situations it is most useful for
add a lot of examples on how to use it
mention whether your framework is stable, beta or alpha. That's important because user need to know that before they start using it
also mention whether you want to keep improving it and keep working on it - most users don't want to use a framework that's abandoned (also keep in mind that a lot of users check your commits to see whether you really are working on it - if your last commit to the repository was months ago then you're not really working on it, so cheating isn't possible)
If you got all this, and people start submitting patches, you can use a patch tool to apply those to your source. Depending on your version control system, you can either use the GNU patch, a diff/patch tool that comes with your version control or maybe even a GUI tool that helps you with this. SVN doesn't have a patch tool (yet), but 'svn diff' will create a patchfile which you can then apply with the GNU patch tool, or in case you're using TortoiseSVN, right-drag the patchfile to your working copy and have TortoiseMerge apply it for you.
And on how to best deal with the community:
answer questions in time, don't wait more than two or three days to answer questions
try to be nice, even with upset and angry people. Only if they keep bothering tell them to (still in a nice way if possible) go elsewhere
always keep discussions about the project on a mailing list. You don't want to repeat the same discussions over and over again - if you have a mailing list, just point users to the archives before the discussion starts all over again
And you should watch the talk "How Open Source Projects Survive Poisonous People (And You Can Too)" - it's really good and tells you a lot on how to deal not just with 'poisonous people' but also how to deal with all people involved in your project.
I'd like to add that you should make it as easy as possible for your users to get the whole thing running and modify the code - these 'power users' can be 'converted' into developers or at least people who send smaller patches.
Don't try to do it all yourself - for open source projects there are several hosting providers that solve most of the problems. I recommend codeplex or google code.
Setting up build scripts will depend a certain amount on what platform you set up, but in general it's easy to add any tool you want into the script once you start using any sort of build script.
If you really need the one step process you describe, you need a build server. I use TeamCity, which I have set up to watch for any changes in svn and trigger build/test whenever something is checked in. The build server will generally be able to perform any steps that you put into the build script.
Read up on Git as an alternative to SVN
free public repository/bug tracker/wiki/fork-enabled community in Github (which hosts symfony and PHPUnit amongst others)
"How do I handle (technically) submissions from other users? How can I ensure that those submissions must be approved before being integrated?" - with Git, pull what you/your closest team finds most interesting to the master branch
Consistent API
be inspired of other public API:s
only change in major versions
guessable
Interesting for both users & developers
clear goal (your roadmap - excellent)
useful, contra everything else available
easy to use, but still not easy-enough-to-write/maintain-yourself
You could check out either Ant or Phing to build your project. Include CodeSniffer in the build and you'll save time checking for basic formatting errors/differences.
These are all technical tips, about the soft part... treat humans with respect, a lot of interest and be overly excited about their contributions and make them feel that they're not wasting their time. That would appeal to me.
Take a look at Karl Fogel's book on Producing Open Source Software. It probably has everything that you asked.
You should also plan for engaging the community. I'd recommend reading Jono Bacon's The Art of Community [http://www.artofcommunityonline.org/].
You have a great set of ideas to start. You might have to start by trimming them down! Ask yourself what's necessary for a first release.
For automating the builds and tests, the scripting can be done with ant, maven or phing for PHP projects.
You'll probably need a host so you can demo the product. For PHP that is pretty easy to find.
You need an open source hosting provider-- especially github (but also google code, source forge, etc). Github provides bug tracking, default licenses, blog and great mechanisms for accepting changes from the community. Built on git, it facilitates distributed projects quite well.
Although it's good to have a one-step build and install in place, automating integration of others changes probably isn't important (or desirable) off the bat.
Good luck!
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
I've used a WordPress blog and a Screwturn Wiki (at two separate jobs) to store private, company-specific KB info, but I'm looking for something that was created to be a knowledge base. Specifically, I'd like to see:
Free/low cost
Simple method for users to subscribe to KB (or just sections) to get updates
Ability to do page versioning/audit changes
Limit access to certain pages for certain users
Very simple method of posting/editing articles
Very simple method of adding images to articles
Excellent (fast, accurate) searching abilities
Ability to rate and comment on articles
I liked using the Wordpress blog because it allowed me to use Live Writer to add/edit articles and images, but it didn't have page versioning (that I could see).
I like using Screwturn wiki because of it's ability to track article versions, and I like it's clean look, but some non-technical people balk at the input and editing.
I second Luke's answer.
I can Recommend Confluence and here is why:
I tested extensively many commercial and free Wiki based solutions. Not a single one is a winner on all accounts, including confluence. Let me try to make your quest a little shorter by summarizing what I have learned to be a pain and what is important:
WYSIWYG is a most have feature for the Enterprise. A wiki without it, skip it
Saying that, in reality, WYSIWYG doesn't work perfectly. It is more of a feature you must have to get the casual users not be afraid of the monster, and start using it. But you and anyone that wants to seriously create content, will very quickly get used to the wiki markup. it is faster and more reliable.
You need good permissions controls (who can see, edit etc' a page). confluence has good, but I have my complaints (to complicated to be put here)
You will want a good export feature. Most will give you a single page "PDF" export, but you need much more. For example, lets say you have an FAQ, you want to export the entire FAQ right? will that work?
Macros: you want a community creating macros. You asked for example about the ability to rate pages, here is a link to a Macro for Confluence that lets you do that
Structure: you want to be able to say that a page is a child of a different page, and be able to browse the data. The wikipedia model, of orphaned pages with no sturcture will not work in the Enterprise. (think FAQ, you want to have a hierarchy no?)
Ability to easily attache picture to be embedded in the body of the page/article. In confluence, you need to upload the image and then can embed it, it could be a little better (CTR+V) but I guess this is easy enough for 80% of the users.
At the end of the day, remember that a Wiki will be valuable to you the more flexible it is. It needs to be a "blank" canvas, and your imagination is then used to "build" the application. In Confluence, I found 3 different "best practices" on how to create a FAQ. That means I can implement MANY things.
Some examples (I use my Wiki for)
FAQ: any error, problem is logged. Used by PS and ENG. reduced internal support time dramatically
Track account status: I implemetned sophisticated "dashboard" that you can see at a glance which customer is at what state, the software version they have, who in the company 'owns" the custoemr etc'
Product: all documentation, installation instructions, the "what's new" etc
Technical documentation, DB structure and what the tables mean
HR: contact list, Document repository
My runner up (15 month ago) was free Deki_Wiki, time has passed, so I don't know if this would be still my runner up.
good luck!
I've also been investigating wiki software for use as a KB, but it is tricky to find something that is easy to use for non-technical people. There are many wikis that attempt to provide WYSIWYG editing, but most of the software I've found generates nasty inefficient html markup from the WYSIWYG editor.
One notable exception to this is Confluence which generates wiki syntax from a WYSIWYG editor. This still isn't perfect (show me a WYSIWYG editor that is) but is a pretty good compromise between retaining simple wiki syntax for those who like it and allowing non-technical users to contribute content. The only problem is that Confluence isn't free ($1,200 for 25 user license).
Edit: I also tried DekiWiki and while the UI is nice it doesn't seem to be quite ready for primetime (suffers terribly from the bad WYSIWYG output disease mentioned above). Also seems like they lack direction as there are so many different ways of accomplishing the same task.
Cerberus - it's more a full featured Help Desk/Issue Tracking system but it has a nice KB solution built in. It can be free but they do have a low cost pay version that is also very good.
Personally I use MediaWiki for this purpose. I've tried a number of other free and paid wikis (including Confluence) and have always been impressed with MediaWiki's simplicity and ease of use.
I have MediaWiki installed on a thumb drive (using XAMPP from PortableApps), which I use mostly as a personal knowledge base/code snippet repository. I can take it with me wherever I go, and view/edit it from any computer I'm using.
I think Drupal is a very possible choice. It has a lot of built-in support for book-type information capturing.
And there is a rich collection of user generated modules which you can use to enhance the features.
I think it has almost all the features you ask for out of the box.
Drupal CMS Benefits
We've been using a combination of
TWiki
OpenGrok for the codebase
usenet
LotusNotes based system
As long as there is a google search appliance pointed at these things I think it's ok to have any or many versions as long as people use them